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

  • Artículo

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 LLM e IA generativa, consulte Modelos básicos de consultas.

Requisitos

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

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

API de REST

Puntuar un modelo donde se acepta el formato de entrada de los registros de dataframe.

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

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:

  1. Abra el conjunto de datos que desea puntuar.

  2. Vaya a Transformar datos.

  3. Haga clic con el botón derecho en el panel izquierdo y seleccione Crear nueva consulta.

  4. Vaya a Ver > Editor avanzado.

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

  6. Asigne a la consulta el nombre del modelo deseado.

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