Method: projects.predict

Performs online prediction on the data in the request.

O AI Platform Prediction implementa um verbo predict personalizado em cima de um método HTTP POST. O método predict realiza a previsão nos dados na solicitação.

O URL é descrito na sintaxe da anotação HTTP da API do Google (em inglês):

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

O parâmetro name é obrigatório. Ele precisa conter o nome do modelo e, opcionalmente, uma versão. Se você não especificar uma versão com o modelo, será usada a versão padrão dele.

Veja este exemplo que mostra o modelo e a versão:

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

Veja este exemplo que mostra apenas o modelo. É usada a versão padrão para o modelo:

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

Nesta página, descrevemos o formato do corpo da solicitação de previsão e do corpo da resposta. Se você quiser um exemplo de código que mostra como enviar uma solicitação de previsão, consulte o guia sobre Como solicitar previsões on-line.

Detalhes do corpo da solicitação

TensorFlow

O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:

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

O objeto instances[] é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões.

A estrutura de cada elemento da lista é determinada pela definição de entrada do modelo. As instâncias podem incluir entradas nomeadas, como objetos, ou conter apenas valores sem rótulo.

Nem todos os dados incluem entradas nomeadas. Algumas instâncias são valores JSON simples como booleanos, números ou strings. No entanto, as instâncias costumam ser listas de valores simples ou listas aninhadas complexas.

Veja abaixo alguns exemplos de corpo de solicitação.

Dados CSV com cada linha codificada como um valor de string:

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

Texto simples:

{"instances": ["the quick brown fox", "the lazy dog"]}

Frases codificadas como listas de palavras (vetores de strings):

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

Valores de ponto flutuante escalares:

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

Vetores de números inteiros:

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

Tensores (neste caso, bidimensionais):

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

Imagens, que podem ser representadas de maneiras diferentes. Neste esquema de codificação, as duas primeiras dimensões representam as linhas e colunas da imagem. Já a terceira dimensão contém listas (vetores) dos valores R, G e B de cada pixel:

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

Codificação de dados

As strings JSON precisam ser codificadas em UTF-8. Para enviar dados binários, é necessário codificar os dados em base64 e marcá-los como binários. Para marcar uma string JSON como binária, substitua-a por um objeto JSON com um único atributo denominado b64:

{"b64": "..."} 

O exemplo a seguir mostra duas instâncias tf.Examples serializadas, que exigem codificação base64 (dados falsos, apenas para fins ilustrativos):

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

O exemplo a seguir mostra duas strings de byte de imagem JPEG que exigem a codificação base64 (dados meramente ilustrativos):

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

Vários tensores de entrada

Alguns modelos têm um gráfico subjacente do TensorFlow que aceita vários tensores de entrada. Nesse caso, use os nomes dos pares JSON de nome/valor para identificar esses tensores:

Para um gráfico com os aliases de tensor de entrada "tag" (string) e "image" (string codificada em Base64), use o seguinte:

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

Para um gráfico com os aliases de tensor de entrada "tag" (string) e "image" (matriz tridimensional com ints de 8 bits), use o seguinte:

{
  "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

O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:

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

O objeto instances[] é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões. No exemplo a seguir, cada instância de entrada é uma lista de floats:

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

A dimensão das instâncias de entrada precisa corresponder ao que seu modelo espera. Por exemplo, se o modelo precisar de três recursos, o comprimento de cada instância de entrada será 3.

XGBoost

O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:

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

O objeto instances[] é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões. No exemplo a seguir, cada instância de entrada é uma lista de floats:

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

A dimensão das instâncias de entrada precisa corresponder ao que seu modelo espera. Por exemplo, se o modelo precisar de três recursos, o comprimento de cada instância de entrada será 3.

O AI Platform Prediction não oferece suporte à representação esparsa de instâncias de entrada para XGBoost.

O serviço de previsão on-line interpreta zeros e NaNs de maneira diferente. Se o valor de um recurso for zero, use 0.0 na entrada correspondente. Se o valor de um elemento estiver ausente, use NaN na entrada correspondente.

O exemplo a seguir representa uma solicitação de previsão com uma única instância de entrada, em que o valor do primeiro recurso é 0.0, o valor do segundo recurso é 1.1 e o valor do terceiro está ausente:

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

Rotina de previsão personalizada

O corpo da solicitação contém dados com a seguinte estrutura na representação JSON:

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

O objeto instances[] é obrigatório e precisa conter a lista de instâncias para as quais você receberá previsões.

Como opção, é possível fornecer outros pares de chave-valor JSON válidos. O AI Platform Prediction analisa o JSON e fornece esses campos ao método predict da classe Predictor como entradas no dicionário **kwargs.

Como estruturar a lista de instâncias

A estrutura de cada elemento da lista de instâncias é determinada pelo método predict da classe Predictor. As instâncias podem incluir entradas nomeadas, como objetos, ou conter apenas valores sem rótulo.

Nem todos os dados incluem entradas nomeadas. Algumas instâncias são valores JSON simples como booleanos, números ou strings. No entanto, as instâncias costumam ser listas de valores simples ou listas aninhadas complexas.

Veja abaixo alguns exemplos de corpo de solicitação.

Dados CSV com cada linha codificada como um valor de string:

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

Texto simples:

{"instances": ["the quick brown fox", "the lazy dog"]}

Frases codificadas como listas de palavras (vetores de strings):

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

Valores de ponto flutuante escalares:

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

Vetores de números inteiros:

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

Tensores (neste caso, bidimensionais):

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

Imagens, que podem ser representadas de maneiras diferentes. Neste esquema de codificação, as duas primeiras dimensões representam as linhas e colunas da imagem. Já a terceira dimensão contém listas (vetores) dos valores R, G e B de cada pixel:

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

Vários tensores de entrada

Alguns modelos têm um gráfico subjacente do TensorFlow que aceita vários tensores de entrada. Nesse caso, use os nomes dos pares JSON de nome/valor para identificar esses tensores:

Para um gráfico com os aliases de tensor de entrada "tag" (string) e "image" (matriz tridimensional com ints de 8 bits), use o seguinte:

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

Detalhes do corpo da resposta

As respostas são muito semelhantes às solicitações.

Se a chamada for bem-sucedida, o corpo da resposta terá uma entrada de previsão por instância no corpo da solicitação, dadas na mesma ordem:

{
  "predictions": [
    {
      object
    }
  ]
}

Se a previsão falhar em qualquer instância, o corpo da resposta não terá previsões. Em vez disso, ele inclui uma única entrada de erro:

{
  "error": string
}

O objeto predictions[] contém a lista de previsões, uma para cada instância na solicitação. Para uma rotina de previsão personalizada (Beta), predictions contém o valor de retorno do método predict da classe Predictor, serializado como JSON.

Em caso de erro, a string error contém uma mensagem descrevendo o problema. Se ocorrer um erro durante o processamento de qualquer instância, ele será retornado em vez de uma lista de previsão.

Há uma previsão por instância, mas o formato da previsão não está diretamente relacionado ao da instância. As previsões recebem o formato especificado no conjunto de saídas definido no modelo. O conjunto de previsões é retornado em uma lista JSON. Cada membro da lista pode ser um valor simples, uma lista ou um objeto JSON de qualquer complexidade. Caso seu modelo tenha mais de um tensor de saída, cada previsão será um objeto JSON que contém um par de nome/valor para cada saída. Os nomes identificam os aliases de saída no gráfico.

Exemplos de corpo de resposta

TensorFlow

Nos exemplos a seguir, mostramos algumas respostas possíveis:

  • Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:

    {"predictions": [5, 4, 3]}
    
  • Um conjunto mais complexo de previsões, cada uma contendo dois valores nomeados que correspondem aos tensores de saída, denominados label e scores, respectivamente. O valor de label é a categoria prevista ("carro" ou "praia") e scores contém uma lista de probabilidades para essa instância nas categorias possíveis.

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • Resposta quando há um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}
    

scikit-learn

Nos exemplos a seguir, mostramos algumas respostas possíveis:

  • Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:

    {"predictions": [5, 4, 3]}
    
  • Resposta quando há um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}
    

XGBoost

Nos exemplos a seguir, mostramos algumas respostas possíveis:

  • Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:

    {"predictions": [5, 4, 3]}
    
  • Resposta quando há um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}
    

Rotina de previsão personalizada

Nos exemplos a seguir, mostramos algumas respostas possíveis:

  • Conjunto simples de previsões de três instâncias de entrada, em que cada previsão é um valor inteiro:

    {"predictions": [5, 4, 3]}
    
  • Um conjunto mais complexo de previsões, cada uma contendo dois valores nomeados que correspondem aos tensores de saída, denominados label e scores, respectivamente. O valor de label é a categoria prevista ("carro" ou "praia") e scores contém uma lista de probabilidades para essa instância nas categorias possíveis.

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • Resposta quando há um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}
    

Especificação da API

Na seção a seguir, descrevemos a especificação do método predict, conforme definido no documento de descoberta do AI Platform Training e da API Prediction. Consulte as seções anteriores deste documento para informações detalhadas sobre o 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.