Prever detalhes da solicitação

Com o método predict, você realiza a previsão nos dados da solicitação.

Nesta página, você verá a descrição do formato do corpo de uma solicitação de predição e da resposta recebida, além do formato do URL da solicitação HTTP. Para um exemplo de código que mostre como enviar uma solicitação de predição, leia o guia sobre como solicitar predições on-line com o TensorFlow e o tutorial sobre como receber predições on-line com o scikit-learn e o XGBoost.

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&gt|<object>,
    ...
  ]
}

O objeto instances[] é obrigatório e precisa incluir a lista das instâncias que serão submetidas à predição.

A estrutura de cada elemento da lista é determinada pela definição de entrada do seu 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", "la bruja le dio"]}

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

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

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, é preciso substituí-la por um objeto JSON com um único atributo chamado b64:

{"b64": "..."} 

No exemplo a seguir, há duas instâncias tf.Examples serializadas em que a codificação base64 é obrigatória (dados meramente 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 incluir a lista das instâncias que serão submetidas à previsão. 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 incluir a lista das instâncias que serão submetidas à previsão. 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 provavelmente será três.

O AI Platform não aceita a representação esparsa de instâncias de entrada para o XGBoost.

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

O exemplo a seguir representa uma solicitação de prediçã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 predição personalizada

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

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

O objeto instances[] é obrigatório e precisa incluir a lista das instâncias que serão submetidas à predição.

Como opção, é possível fornecer outros pares de chave-valor JSON válidos. O AI Platform analisa o JSON e envia esses campos para o método predict da sua 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 sua 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", "la bruja le dio"]}

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

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

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

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 predições, uma para cada instância na solicitação. Para uma rotina de predição personalizada (Beta), predictions contém o valor de retorno do método predict da sua classe Predictor, serializado como JSON.

Quando há um erro, a string error inclui uma mensagem que descreve 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

Os exemplos a seguir mostram algumas respostas possíveis:

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

    {"predictions": [5, 4, 3]}
    
  • Conjunto mais complexo de previsões. Cada uma contém dois valores nomeados que correspondem aos tensores de saída, chamados de label e scores, respectivamente. O valor de label é a categoria prevista ("car" ou "beach"), e scores inclui uma lista de probabilidades dessa instância em todas as 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

Os exemplos a seguir mostram algumas respostas possíveis:

  • Conjunto simples de predições de três instâncias de entrada, em que cada prediçã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

Os exemplos a seguir mostram algumas respostas possíveis:

  • Conjunto simples de predições de três instâncias de entrada, em que cada prediçã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 predição personalizada

Os exemplos a seguir mostram algumas respostas possíveis:

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

    {"predictions": [5, 4, 3]}
    
  • Conjunto mais complexo de previsões. Cada uma contém dois valores nomeados que correspondem aos tensores de saída, chamados de label e scores, respectivamente. O valor de label é a categoria prevista ("car" ou "beach"), e scores inclui uma lista de probabilidades dessa instância em todas as 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"}
    

Formato do URL HTTP

Para um exemplo de código que mostre como enviar uma solicitação de predição, leia o guia sobre como solicitar predições on-line com o TensorFlow e o tutorial sobre como receber predições on-line com o scikit-learn e o XGBoost. No resto da página, você verá o formato de URL HTTP implementado pela AI Platform, para os que precisam de uma descrição detalhada.

O AI Platform implementa um verbo predict personalizado sobre um método HTTP POST. O URL é descrito na sintaxe da anotação HTTP da API do Google:

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

O parâmetro name é necessá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 especifica o modelo e a versão:

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

Veja este exemplo que especifica apenas o modelo. A versão padrão é usada:

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

O segmento :predict, no final do caminho, indica que o AI Platform usa um verbo personalizado conforme definido na documentação sobre HTTP da API do Google. Nesse caso, o verbo personalizado é predict.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…