Detalles de la solicitud predict

Con el método predict se realiza la predicción de los datos en la solicitud.

En esta página, se describe el formato del cuerpo de la solicitud de predicción y el del cuerpo de la respuesta, así como el formato de URL en la solicitud HTTP. A fin de ver un código de ejemplo en el que se muestra cómo enviar una solicitud de predicción, consulta la guía para solicitar predicciones en línea con TensorFlow el instructivo sobre cómo obtener predicciones en línea con scikit-learn y XGBoost.

Cuerpo de la solicitud

TensorFlow

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

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

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

La estructura de cada elemento de la lista de instancias se determina con la definición de entrada de tu modelo. En las instancias se pueden incluir entradas con nombre (como objetos) o únicamente valores sin etiqueta.

No en todos los datos se incluyen entradas con nombre. Algunas instancias son valores JSON sencillos (booleano, número o string). Sin embargo, las instancias suelen ser listas de valores sencillos o listas anidadas complejas.

A continuación, se presentan algunos ejemplos de cuerpos de solicitud.

Datos CSV con cada fila codificada como un valor de string:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

Texto sin formato:

{"instances": ["the quick brown fox", "la bruja le dio"]}

Oraciones codificadas como listas de palabras (vectores de strings):

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

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 de dos dimensiones):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

Imágenes que se pueden representar de diferentes maneras. En este esquema de codificación, las dos primeras dimensiones representan las filas y columnas de la imagen, y la tercera dimensión contiene listas (vectores) de los valores R, G y B para cada píxel:

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

Codificación de datos

Las strings JSON se deben codificar como UTF-8. Para enviar datos binarios, debes codificar los datos en base64 y marcarlos como binarios. Para marcar una string JSON como binaria, reemplázala por un objeto JSON con un atributo único denominado b64:

{"b64": "..."} 

En el siguiente ejemplo, se muestran dos instancias tf.Examples serializadas que requieren codificación base64 (datos ficticios, solo para fines ilustrativos):

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

En el siguiente ejemplo, se muestran dos strings de bytes de imagen JPEG, que requieren codificación base64 (datos ficticios, solo para fines ilustrativos):

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

Tensores de varias entradas

Algunos modelos tienen un grafo de TensorFlow subyacente con el que se aceptan varios tensores de entrada. En este caso, usa los nombres de los pares de nombre/valor JSON para identificar los tensores de entrada, como se muestra en los siguientes ejemplos:

Para un grafo con alias de tensor de entrada "image" (string codificada en base64) y "tag" (string):

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

Para un grafo con alias de tensor de entrada "image" (arreglo de 3 dimensiones de entradas de 8 bits) y "tag" (string):

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

scikit-learn

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

{
  "instances": [
    <simple list>,
    ...
  ]
}

El objeto instances[] es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones. En el siguiente ejemplo, cada instancia de entrada es una lista de flotantes:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

La dimensión de las instancias de entrada debe coincidir con lo que se espera con tu modelo. Por ejemplo, si tu modelo requiere tres características, la longitud de cada instancia de entrada debe ser 3.

XGBoost

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

{
  "instances": [
    <simple list>,
    ...
  ]
}

El objeto instances[] es obligatorio y debe contener la lista de instancias para las que se pueden obtener predicciones. En el siguiente ejemplo, cada instancia de entrada es una lista de flotantes:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

La dimensión de las instancias de entrada debe coincidir con lo que se espera con tu modelo. Por ejemplo, si tu modelo requiere tres características, la longitud de cada instancia de entrada debe ser 3.

Cloud ML Engine no admite la representación dispersa de instancias de entrada para XGBoost.

Con el servicio de predicción en línea, los ceros y los NaN se interpretan de manera diferente. Si el valor de una característica es cero, usa 0.0 en la entrada correspondiente. Si falta el valor de una característica, usa NaN en la entrada correspondiente.

En el siguiente ejemplo, se representa una solicitud de predicción con una instancia de entrada única, en la que el valor de la primera característica es 0.0, el valor de la segunda característica es 1.1 y falta el valor de la tercera característica:

{"instances": [[0.0, 1.1, NaN]]}

Cuerpo de la respuesta

Las respuestas son muy similares a las solicitudes.

Si la llamada es correcta, el cuerpo de la respuesta contiene una entrada de predicción por instancia en el cuerpo de la solicitud, que se da en el mismo orden:

{
  "predictions": [
    {
      object
    }
  ]
}

Si en la predicción se producen errores para alguna instancia, el cuerpo de la respuesta no contiene predicciones. En su lugar, contiene una entrada de error:

{
  "error": string
}

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

En caso de que se produzca un error, la string error contiene un mensaje que describe el problema. Se muestra el error en lugar de una lista de predicciones si se produjo mientras se procesaban las instancias.

A pesar de que hay una predicción por instancia, el formato de una predicción no está relacionado directamente con el formato de una instancia. Con las predicciones, se toma cualquier formato que se especifique en la colección de salidas definida en el modelo. La colección de predicciones se muestra en una lista JSON. Cada miembro de la lista puede ser un valor sencillo, una lista o un objeto JSON de cualquier complejidad. Si tu modelo tiene más de un tensor de salida, cada predicción será un objeto JSON que contiene un par nombre/valor para cada salida. Con los nombres se pueden identificar los alias de salida en el grafo.

Ejemplos de cuerpo de respuesta

TensorFlow

En los siguientes ejemplos, se muestran algunas respuestas posibles:

  • Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:

    {"predictions": [5, 4, 3]}
    
  • Un conjunto de predicciones más complejo, en el que cada predicción contiene dos valores nombrados que corresponden a los tensores de salida, con los nombres label y scores respectivamente. El valor de label es la categoría con predicción ("auto" o "beach") y scores contiene una lista de probabilidades para esa instancia en todas las categorías posibles.

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:

    {"error": "Divide by zero"}
    

scikit-learn

En los siguientes ejemplos, se muestran algunas respuestas posibles:

  • Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:

    {"predictions": [5, 4, 3]}
    
  • Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:

    {"error": "Divide by zero"}
    

XGBoost

En los siguientes ejemplos, se muestran algunas respuestas posibles:

  • Un conjunto de predicciones sencillo para tres instancias de entrada, en el que cada predicción es un valor de número entero:

    {"predictions": [5, 4, 3]}
    
  • Una respuesta cuando se produce un error en el procesamiento de una instancia de entrada:

    {"error": "Divide by zero"}
    

Formato de URL HTTP

A fin de ver un código de ejemplo que muestra cómo enviar una solicitud de predicción, consulta la guía para solicitar predicciones en línea con TensorFlow y el instructivo sobre cómo obtener predicciones en línea con scikit-learn y XGBoost. En el resto de esta página, se describe el formato de URL HTTP que Cloud ML Engine implementó, para aquellas en las que es necesario dar una descripción detallada.

Con Cloud ML Engine, se implementa un verbo predict personalizado sobre un método HTTP POST. La URL se describe en la sintaxis de anotación HTTP de la API de Google:

POST https://ml.googleapis.com/v1/{name=projects/**}:predict

El parámetro name es obligatorio. Debe contener el nombre de tu modelo y una versión (opcional). Si especificas un modelo sin una versión, se usará la versión predeterminada para ese modelo.

Ejemplo en el que se especifican el modelo y la versión:

POST https://ml.googleapis.com/v1/projects/my-project/models/my-model/versions/my-version:predict

Ejemplo en el que se especifica solo un modelo. Se usa la versión predeterminada para ese modelo:

POST https://ml.googleapis.com/v1/projects/my-project/models/my-model:predict

Con el segmento :predict al final de la ruta de acceso, se indica que Cloud ML Engine usa un verbo personalizado, como se define en la documentación de HTTP de la API de Google. En este caso, el verbo personalizado es predict.

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Cloud Machine Learning Engine (Cloud ML Engine)