Dar formato a las solicitudes de predicción

de GDC.

Usa las predicciones online cuando hagas solicitudes en respuesta a la entrada de una aplicación o en situaciones que requieran inferencias oportunas (respuestas en tiempo real).

En esta página se explica cómo dar formato a las solicitudes de predicción online mediante la API Online Prediction para tus modelos entrenados previamente y se proporcionan ejemplos de solicitudes y respuestas. Una vez que hayas formateado tu solicitud, podrás obtener una predicción online.

Antes de empezar

Antes de dar formato a una solicitud para hacer predicciones online, sigue estos pasos:

  1. Exporta el artefacto de tu modelo para la predicción.

  2. Despliega el recurso de modelo en un endpoint.

    Esta acción asocia recursos de computación al modelo para que pueda ofrecer predicciones online con baja latencia.

  3. Comprueba el estado del DeployedModel recurso personalizado de tu modelo y asegúrate de que esté listo para aceptar solicitudes de predicción:

    kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f DEPLOYED_MODEL_NAME.yaml -o jsonpath='{.status.primaryCondition}'

    Haz los cambios siguientes:

    • PREDICTION_CLUSTER_KUBECONFIG: la ruta al archivo kubeconfig del clúster de predicción.
    • DEPLOYED_MODEL_NAME: el nombre del archivo de definición DeployedModel.

    La condición principal debe mostrar que el DeployedModel está listo.

    En el siguiente resultado se muestra un ejemplo de respuesta:

    {"firstObservedTime":"2024-01-19T01:18:30Z","lastUpdateTime":"2024-01-19T01:35:47Z","message":"DeployedModel is ready", "observedGeneration":1, "reason":"Ready", "resourceName":"my-tf-model","type":"DeployedModel"}

  4. Comprueba el estado del recurso personalizado Endpoint y asegúrate de que esté listo para aceptar solicitudes de predicción:

    kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f ENDPOINT_NAME.yaml -o jsonpath='{$.status.conditions[?(@.type == "EndpointReady")]}'

    Haz los cambios siguientes:

    • PREDICTION_CLUSTER_KUBECONFIG: la ruta al archivo kubeconfig del clúster de predicción.
    • ENDPOINT_NAME: el nombre del archivo de definición Endpoint.

    El campo status de la condición EndpointReady debe mostrar un valor True.

    En el siguiente resultado se muestra un ejemplo de respuesta:

    {"lastTransitionTime":"2024-01-19T05:12:26Z","message":"Endpoint Ready", "observedGeneration":1,"reason":"ResourceReady","status":"True","type":"EndpointReady"}%

Formatear las entradas para las predicciones online

La predicción online tiene dos métodos para enviar solicitudes:

  • Solicitud de predicción: envía una solicitud al método predict para obtener una predicción online.
  • Solicitud de predicción sin formato: envía una solicitud al método rawPredict, que te permite usar una carga útil HTTP arbitraria en lugar de seguir un formato JSON.

Si necesitas una latencia baja, obtén predicciones sin procesar, ya que rawPredict omite los pasos de serialización y reenvía directamente la solicitud al contenedor de predicción.

En esta sección se muestra cómo dar formato y codificar las instancias de entrada de predicción con JSON, lo que es obligatorio si utilizas el método predict. No es necesario que proporciones esta información si utilizas el método rawPredict.

Si usas el SDK de Vertex AI para Python para enviar solicitudes de predicción, especifica la lista de instancias sin el campo instances. Por ejemplo, especifica [ ["the","quick","brown"], ... ] en lugar de { "instances": [ ["the","quick","brown"], ... ] }.

Formatear instancias como cadenas JSON

El formato básico de la predicción online es una lista de instancias de datos. Pueden ser listas de valores sin formato o miembros de un objeto JSON, en función de cómo hayas configurado las entradas en tu aplicación de entrenamiento. Los modelos de TensorFlow pueden aceptar entradas más complejas.

En el siguiente ejemplo se muestra un tensor de entrada y una clave de instancia de un modelo de TensorFlow:

 {"values": [1, 2, 3, 4], "key": 1}

La composición de la cadena JSON puede ser compleja, siempre que siga estas reglas:

  • El nivel superior de los datos de instancia debe ser un objeto JSON, que es un diccionario de pares clave-valor.

  • Los valores individuales de un objeto de instancia pueden ser cadenas, números o listas. No puedes insertar objetos JSON.

  • Las listas solo pueden contener elementos del mismo tipo (incluidas otras listas). No mezcles cadenas y valores numéricos.

Las instancias de entrada de la predicción online se envían como cuerpo del mensaje de la llamada predict. Consulta más información sobre los requisitos de formato del cuerpo de la solicitud.

Convierte cada instancia en un elemento de una matriz JSON y proporciona la matriz como el campo instances de un objeto JSON, como en el siguiente ejemplo:

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

Codificar datos binarios para la entrada de predicciones

No puedes dar formato a los datos binarios como las cadenas codificadas en UTF-8 que admite JSON. Si tiene datos binarios en sus entradas, utilice la codificación base64 para representarlos. Necesitas el siguiente formato especial:

  • Da formato a la cadena codificada como un objeto JSON con una sola clave llamada b64. En Python 3, la codificación base64 genera una secuencia de bytes. Convierte esta secuencia en una cadena para que se pueda serializar en JSON:

    {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}

  • En el código de tu modelo de TensorFlow, asigna nombres a los alias de los tensores de entrada y salida binarios para que terminen en _bytes.

Ejemplos de solicitudes y respuestas

En esta sección se describe el formato de los cuerpos de las solicitudes y respuestas de Predicción online, con ejemplos de TensorFlow y PyTorch.

Detalles del cuerpo de la solicitud

TensorFlow

El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

El objeto instances[] es obligatorio y debe contener la lista de instancias de las que se quieren obtener predicciones.

La estructura de cada elemento de la lista de instancias se determina mediante la definición de entrada de tu modelo. Las instancias pueden incluir entradas con nombre (como objetos) o contener solo valores sin etiqueta.

No todos los datos incluyen entradas con nombre. Algunas instancias son valores JSON (booleanos, números o cadenas). Sin embargo, las instancias suelen ser listas de valores o listas anidadas complejas.

A continuación se muestran algunos ejemplos de cuerpos de solicitud:

  • Datos CSV con cada fila codificada como un valor de cadena:
{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}
  • Texto sin formato:
{"instances": ["the quick brown fox", "the lazy dog"]}
  • Frases codificadas como listas de palabras (vectores de cadenas):
{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}
  • Valores escalares de punto flotante:
{"instances": [0.0, 1.1, 2.2]}
  • Vectores de números enteros:
{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}
  • Tensores (en este caso, tensores bidimensionales):
{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}
  • Imágenes, que se pueden representar de diferentes formas:

En este esquema de codificación, las dos primeras dimensiones representan las filas y las columnas de la imagen, y la tercera dimensión contiene listas (vectores) de los valores R, G y B de cada píxel:

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

Codificación de datos

Las cadenas JSON deben codificarse como UTF-8. Para enviar datos binarios, debes codificarlos en base64 y marcarlos como binarios. Para marcar una cadena JSON como binaria, sustitúyala por un objeto JSON con un solo atributo llamado b64:

{"b64": "..."}

En el siguiente ejemplo se muestran dos instancias serializadas de tf.Examples que requieren codificación en Base64 (datos falsos con fines ilustrativos):

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

En el siguiente ejemplo se muestran dos cadenas de bytes de imágenes JPEG que requieren codificación Base64 (datos falsos, solo con fines ilustrativos):

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

Varios tensores de entrada

Algunos modelos tienen un gráfico de TensorFlow subyacente que acepta varios tensores de entrada. En este caso, usa los nombres de los pares clave-valor de JSON para identificar los tensores de entrada.

Para un gráfico con los alias de tensor de entrada tag (cadena) y image (cadena codificada en base64):

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

Para un gráfico con los alias de tensor de entrada tag (cadena) y image (matriz tridimensional de números enteros de 8 bits):

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

PyTorch

Si tu modelo usa un contenedor precompilado de PyTorch, los controladores predeterminados de TorchServe esperan que cada instancia se envuelva en un campo data. Por ejemplo:

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

Detalles del cuerpo de la respuesta

Si la llamada se realiza correctamente, el cuerpo de la respuesta contiene una entrada de predicción por instancia en el cuerpo de la solicitud, en el mismo orden:

{
  "predictions": [
    {
      object
    }
  ],
  "deployedModelId": string
}

Si la predicción falla en alguna instancia, el cuerpo de la respuesta no contendrá ninguna predicción. En su lugar, contiene una sola entrada de error:

{
  "error": string
}

El objeto predictions[] contiene la lista de predicciones, una por cada instancia de la solicitud.

Si se produce un error, la cadena error contiene un mensaje que describe el problema. El error se devuelve en lugar de una lista de predicciones si se produce un error al procesar alguna instancia.

Aunque hay una predicción por instancia, el formato de una predicción no está directamente relacionado con el formato de una instancia. Las predicciones adoptan el formato que se especifica en la colección de salidas definida en el modelo. La colección de predicciones se devuelve en una lista JSON. Cada miembro de la lista puede ser un valor, una lista o un objeto JSON de cualquier complejidad. Si tu modelo tiene más de un tensor de salida, cada predicción es un objeto JSON que contiene un par clave-valor por cada salida. Las claves identifican los alias de salida del gráfico.

Ejemplos de cuerpos de respuesta

En los siguientes ejemplos se muestran algunas respuestas posibles de TensorFlow:

  • Un conjunto de predicciones para tres instancias de entrada, donde cada predicción es un valor entero:

    {"predictions":
  [5, 4, 3],
  "deployedModelId": 123456789012345678
}

  • Un conjunto de predicciones más complejo, cada una de las cuales contiene dos valores con nombre que corresponden a tensores de salida, denominados label y scores, respectivamente. El valor de label es la categoría predicha (coche o playa) y scores contiene una lista de probabilidades de esa instancia en las categorías posibles:

    {
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ],
  "deployedModelId": 123456789012345678
}

  • Respuesta cuando se produce un error al procesar una instancia de entrada:

    {"error": "Divide by zero"}