Puntos de conexión de servicio de consulta para modelos personalizados

Artículo
10/30/2024

En este artículo, aprenderá a dar formato a las solicitudes de puntuación para el modelo servido y a enviar esas solicitudes al punto de conexión de servicio del modelo. La guía es relevante para servir modelos personalizados, que Databricks define como modelos de ML tradicionales o modelos de Python personalizados empaquetados en el formato MLflow. Se pueden registrar en el catálogo de Unity o en el registro del modelo del área de trabajo. Algunos ejemplos son los modelos de transformador scikit-learn, XGBoost, PyTorch y Hugging Face. Consulte Servicio de modelos con Azure Databricks para obtener más información sobre esta funcionalidad y las categorías de modelos compatibles.

Para obtener solicitudes de consulta para cargas de trabajo de IA generativa y LLM, consulte Consulta de modelos de IA generativa.

Requisitos

Un modelo de que sirve al punto de conexión.
Para el SDK de implementaciones de MLflow, se requiere MLflow 2.9 o superior.
Solicitud de puntuación en un formato aceptado.
Para enviar una solicitud de puntuación a través de la API de REST o el SDK de implementación de MLflow, debe tener un token de la API de Databricks.

Importante

Como procedimiento recomendado de seguridad para escenarios de producción, Databricks recomienda usar Tokens de OAuth de máquina a máquina para la autenticación durante la producción.

Para pruebas y desarrollo, Databricks recomienda usar un token de acceso personal que pertenezca a entidades de servicio en lugar de usuarios del área de trabajo. Para crear tókenes para entidades de servicio, consulte Administración de tokens de acceso para una entidad de servicio.

Métodos y ejemplos de consulta

Mosaic AI Model Serving proporciona las siguientes opciones para enviar solicitudes de puntuación a modelos servidos:

Método	Detalles
Interfaz de usuario de servicio	Seleccione Punto de conexión de consulta en la página Punto de conexión de servicio del área de trabajo de Databricks. Introduzca los datos de entrada del modelo en formato JSON y haga clic en Enviar solicitud. Si el modelo tiene un ejemplo de entrada registrado, use Mostrar ejemplo para cargarlo.
REST API	Llame al modelo y consulte el modelo mediante la API de REST. Consulte POST /serving-endpoints/{name}/invocations para más detalles. Para puntuar solicitudes a puntos de conexión que sirven a varios modelos, consulte Consultar modelos individuales detrás de un punto de conexión.
SDK de implementaciones de MLflow	Use la función predict() del SDK’de implementaciones de MLflow para consultar el modelo.
Función SQL	Invoque la inferencia del modelo directamente desde SQL usando la función de SQL `ai_query`. Vea Consulta de un modelo servido con ai_query().

Ejemplo de puntuación de DataFrame de Pandas

El siguiente ejemplo supone un MODEL_VERSION_URI como https://<databricks-instance>/model/iris-classifier/Production/invocations, donde <databricks-instance> es el nombre de su instancia de Databricks, y un token de la API de REST de Databricks llamado DATABRICKS_API_TOKEN.

Consulte formatos de puntuación admitidos.

REST API

Puntuar un modelo donde se acepta el formato de entrada dividido de 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]]
    }]
  }'

Puntuar un modelo donde se acepta el uso de entradas de tensor. Las entradas de tensor deben tener el formato descrito en la documentación de la API de 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 de implementaciones de MLflow

Importante

En el ejemplo siguiente se usa la API de predict() del SDK de implementaciones de 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

Importante

En el ejemplo siguiente se usa la función SQL integrada, ai_query. Esta función está en Versión preliminar pública y la definición podría cambiar. Vea Consulta de un modelo servido con ai_query().

El siguiente ejemplo consulta el modelo detrás del sentiment-analysispunto finaltext con el conjunto de datos y especifica el tipo de retorno de la solicitud.

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

PowerBI

Puede puntuar un conjunto de datos en Power BI Desktop con los pasos siguientes:

Abra el conjunto de datos que desea puntuar.
Vaya a Transformar datos.
Haga clic con el botón derecho en el panel izquierdo y seleccione Crear nueva consulta.
Vaya a Ver > Editor avanzado.

Reemplace el cuerpo de la consulta por el fragmento de código siguiente, después de rellenar un DATABRICKS_API_TOKEN y MODEL_VERSION_URI adecuados.

(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

Asigne a la consulta el nombre del modelo deseado.
Abra el editor de consultas avanzada para el conjunto de datos y aplique la función de modelo.

Ejemplo de entrada de tensor

En el ejemplo siguiente se puntúa un modelo que acepta entradas de tensor. Las entradas de tensor deben tener el formato descrito en la documentación de la API de TensorFlow Serving. Este ejemplo supone un MODEL_VERSION_URI como https://<databricks-instance>/model/iris-classifier/Production/invocations, donde <databricks-instance> es el nombre de su instancia de Databricks, y un token de la API de REST de Databricks llamado 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]]}'

Formatos de puntuación admitidos

En el caso de los modelos personalizados, el Servicio de modelos admite solicitudes de puntuación en la entrada de Tensor o DataFrame de Pandas.

DataFrame de Pandas

Las solicitudes deben enviarse construyendo un Dataframe de Pandas serializado en JSON con una de las claves compatibles y un objeto JSON correspondiente al formato de entrada.

El formato dataframe_split (recomendado) es un DataFrame de Pandas serializado por JSON en la orientación split.

{
  "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 es el Dataframe de Pandas serializado con JSON en la orientación records.

Nota:

Este formato no garantiza la conservación de la ordenación de columnas y se prefiere el formato split antes que el 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 respuesta del punto de conexión contiene la salida del modelo, serializada con JSON, encapsulada en una clave predictions.

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

Entrada de tensor

Cuando su modelo espera tensores, como un modelo de Tensorflow o Pytorch, hay dos opciones de formato compatibles para enviar solicitudes: instances y inputs.

Si tiene varios tensores con nombre por fila, debe tener uno de cada tensor para cada fila.

instances es un formato basado en tensores donde se acepta el uso de tensores que estén en formato de fila. Use este formato si todos los tensores de entrada tienen la misma dimensión en posición 0. En teoría, cada tensor de la lista de instancias podría combinarse con los otros tensores del resto de la lista que tengan el mismo nombre para construir el tensor de entrada completo del modelo. Esto solo sería posible si todos los tensores tienen la misma dimensión en posición 0.
```
{"instances": [ 1, 2, 3 ]}
```
En el ejemplo siguiente se muestra cómo especificar varios tensores con nombre.
```
{
"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, que se usa para enviar consultas con tensores que estén en formato de columna. Esta solicitud es distinta porque el elemento t2 tiene un número diferente de instancias de tensor (3) en relación con los elementos t1 y t3. Por tanto, no será posible representar esta entrada en el formato instances.
```
{
"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 respuesta del punto de conexión tiene el siguiente formato.

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

Ejemplo de cuaderno

Consulte el cuaderno siguiente para ver un ejemplo de cómo probar el punto de conexión de Model Serving con un modelo de Python:

Cuaderno de punto de conexión de servicio del modelo de prueba

Obtener el cuaderno

Recursos adicionales

Tablas de inferencia para supervisar y depurar modelos.
Consulta de modelos de IA generativa.
Guía de depuración para servicio de modelos.

Compartir a través de

Puntos de conexión de servicio de consulta para modelos personalizados

Requisitos

Métodos y ejemplos de consulta

Ejemplo de puntuación de DataFrame de Pandas

REST API

SDK de implementaciones de MLflow

SQL

PowerBI

Ejemplo de entrada de tensor

Formatos de puntuación admitidos

DataFrame de Pandas

Entrada de tensor

Ejemplo de cuaderno

Cuaderno de punto de conexión de servicio del modelo de prueba

Recursos adicionales

Comentarios

Recursos adicionales