Method: projects.predict

Performs online prediction on the data in the request.

AI Platform Prediction implementa un verbo predict personalizado sobre un método HTTP POST. Con el método predict se realiza la predicción de los datos en la solicitud.

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 del modelo y, de manera opcional, una versión. 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/your-project-id/models/your-model-name/versions/your-version-name:predict

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

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name:predict

En esta página, se describe el formato del cuerpo de la solicitud de predicción y del cuerpo de la respuesta. Si deseas ver una muestra de código que muestra cómo enviar una solicitud de predicción, consulta la guía para solicitar predicciones en línea.

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 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 del modelo. En las instancias, se pueden incluir entradas con nombre (como objetos) o solo 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", "the lazy dog"]}

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

{
  "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 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 serializadas tf.Examples que requieren codificación base64 (se usan datos falsos 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 (se usan datos falsos 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 nombre-valor JSON para identificar los tensores de entrada.

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

{
  "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 números de puntos 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 espera el modelo. Por ejemplo, si el modelo requiere tres atributos, 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 números de puntos 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 espera el modelo. Por ejemplo, si el modelo requiere tres atributos, la longitud de cada instancia de entrada debe ser 3.

AI Platform Prediction 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 un atributo es cero, usa 0.0 en la entrada correspondiente. Si falta el valor de un atributo, 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 del primer atributo es 0.0, el del segundo es 1.1 y falta el del tercero:

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

Rutina de predicción personalizada

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

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

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

De forma opcional, puedes proporcionar cualquier otro par clave-valor de JSON válido. AI Platform Prediction analiza el JSON y proporciona estos campos al método predict de la clase de Predictor como entradas en el diccionario **kwargs.

Cómo estructurar la lista de instancias

La estructura de cada elemento de la lista de instancias se determina mediante el método predict de la clase de Predictor. En las instancias, se pueden incluir entradas con nombre (como objetos) o solo 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", "the lazy dog"]}

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

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

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 nombre-valor JSON para identificar los tensores de entrada.

Para un grafo con alias de tensor de entrada “image” (arreglo de 3 dimensiones de entradas de 8 bits) y “tag” (string), usa lo siguiente:

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

Detalles del cuerpo de la respuesta

Las respuestas son muy similares a las solicitudes.

Si la llamada se realiza de forma 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 de la solicitud. Para una rutina de predicción personalizada (Beta), predictions contiene el valor de retorno del método predict de la clase de Predictor, serializado como JSON.

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 este 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 el 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 del cuerpo de la 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 con nombre que corresponden a los tensores de salida, con los nombres respectivos label y scores. El valor de label es la categoría predicha (“automóvil” o “playa”) 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"}
    

Rutina de predicción personalizada

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 con nombre que corresponden a los tensores de salida, con los nombres respectivos label y scores. El valor de label es la categoría predicha (“automóvil” o “playa”) 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"}
    

Especificación de la API

En la siguiente sección, se describe la especificación del método predict como se define en el documento de descubrimiento de la API de entrenamiento y predicción de AI Platform. Consulta las secciones anteriores de este documento para obtener información detallada sobre el método.

HTTP request

POST https://{endpoint}/v1/{name=projects/**}:predict

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version.

Authorization: requires the predict permission on the specified resource.

Authorization requires one or more of the following IAM permissions on the specified resource name:

  • ml.models.predict
  • ml.versions.predict

Request body

The request body contains data with the following structure:

JSON representation
{
  "httpBody": {
    object (HttpBody)
  }
}
Fields
httpBody

object (HttpBody)

Required. The prediction request body. Refer to the request body details section for more information on how to structure your request.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.