Formate os pedidos de previsão

Use previsões online quando estiver a fazer pedidos em resposta à introdução de dados da aplicação ou em situações que exijam inferência atempada (respostas em tempo real).

Esta página mostra como formatar pedidos de previsão online através da API Online Prediction para os seus modelos personalizados e fornece exemplos de pedidos e respostas. Depois de formatar o pedido, pode receber uma previsão online.

Antes de começar

Antes de formatar um pedido para fazer previsões online, execute os seguintes passos:

  1. Exporte o artefacto do modelo para a previsão.

  2. Implemente o recurso do modelo num ponto final.

    Esta ação associa recursos de computação ao modelo para que possa publicar previsões online com baixa latência.

  3. Verifique o estado do recurso personalizado do seu modelo e certifique-se de que está pronto para aceitar pedidos de previsão:DeployedModel

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

    Substitua o seguinte:

    • PREDICTION_CLUSTER_KUBECONFIG: o caminho para o ficheiro kubeconfig no cluster de previsão.
    • DEPLOYED_MODEL_NAME: o nome do ficheiro de definição DeployedModel.

    A condição principal tem de mostrar que o DeployedModel está pronto.

    A saída seguinte mostra uma resposta de exemplo:

    {"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. Verifique o estado do Endpoint recurso personalizado e certifique-se de que está pronto para aceitar pedidos de previsão:

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

    Substitua o seguinte:

    • PREDICTION_CLUSTER_KUBECONFIG: o caminho para o ficheiro kubeconfig no cluster de previsão.
    • ENDPOINT_NAME: o nome do ficheiro de definição Endpoint.

    O campo status da condição EndpointReady tem de mostrar um valor True.

    A saída seguinte mostra uma resposta de exemplo:

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

Formate a entrada para previsões online

A previsão online tem os seguintes dois métodos para enviar pedidos:

  • Pedido de previsão: envie um pedido ao método predict para receber uma previsão online.
  • Pedido de previsão não processado: envie um pedido para o método rawPredict, que lhe permite usar uma carga útil HTTP arbitrária em vez de seguir um formato JSON.

Se precisar de baixa latência, obtenha previsões não processadas porque rawPredict ignora os passos de serialização e encaminha diretamente o pedido para o contentor de previsão.

Esta secção mostra como formatar e codificar as suas instâncias de entrada de previsão usando JSON, o que é necessário se estiver a usar o método predict. Estas informações não são necessárias se estiver a usar o método rawPredict.

Se estiver a usar o SDK do Vertex AI para Python para enviar pedidos de previsão, especifique a lista de instâncias sem o campo instances. Por exemplo, especifique [ ["the","quick","brown"], ... ] em vez de { "instances": [ ["the","quick","brown"], ... ] }.

Formate instâncias como strings JSON

O formato básico para a previsão online é uma lista de instâncias de dados. Podem ser listas simples de valores ou membros de um objeto JSON, consoante a forma como configurou as entradas na aplicação de preparação. Os modelos do TensorFlow podem aceitar entradas mais complexas.

O exemplo seguinte mostra um tensor de entrada e uma chave de instância para um modelo do TensorFlow:

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

A composição da string JSON pode ser complexa, desde que siga estas regras:

  • O nível superior dos dados de instância tem de ser um objeto JSON, que é um dicionário de pares de chave-valor.

  • Os valores individuais num objeto de instância podem ser strings, números ou listas. Não pode incorporar objetos JSON.

  • As listas só podem conter itens do mesmo tipo (incluindo outras listas). Não misture strings e valores numéricos.

Transmite instâncias de entrada para a previsão online como o corpo da mensagem para a chamada predict. Saiba mais acerca dos requisitos de formatação do corpo do pedido.

Faça de cada instância um item numa matriz JSON e forneça a matriz como o campo instances de um objeto JSON, como no exemplo seguinte:

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

Codifique dados binários para a entrada de previsão

Não pode formatar dados binários como as strings codificadas em UTF-8 que o JSON suporta. Se tiver dados binários nas suas entradas, use a codificação base64 para os representar. Precisa da seguinte formatação especial:

  • Formate a string codificada como um objeto JSON com uma única chave denominada b64. No Python 3, a codificação base64 gera uma sequência de bytes. Converta esta sequência numa string para a tornar serializável em JSON:

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

  • No código do modelo do TensorFlow, atribua nomes aos alias dos tensores de entrada e saída binários para que terminem com _bytes.

Exemplos de pedidos e respostas

Esta secção descreve o formato dos corpos de pedidos e respostas de previsão online com exemplos para o TensorFlow e o PyTorch.

Detalhes do corpo do pedido

TensorFlow

O corpo do pedido contém dados com a seguinte estrutura (representação JSON):

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

O objeto instances[] é obrigatório e tem de conter a lista de instâncias para as quais obter previsões.

A estrutura de cada elemento da lista de instâncias é determinada pela definição de entrada do seu modelo. As instâncias podem incluir entradas com nome (como objetos) ou podem conter apenas valores sem etiqueta.

Nem todos os dados incluem entradas com nome. Algumas instâncias são valores JSON (booleanos, numéricos ou de string). No entanto, as instâncias são frequentemente listas de valores ou listas aninhadas complexas.

Seguem-se alguns exemplos de corpos de pedidos:

  • 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 escalares de vírgula flutuante:
{"instances": [0.0, 1.1, 2.2]}
  • Vetores de números inteiros:
{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}
  • Tensores (neste caso, tensores bidimensionais):
{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}
  • Imagens, que podem ser representadas de diferentes formas:

Neste esquema de codificação, as duas primeiras dimensões representam as linhas e as colunas da imagem, e a terceira dimensão contém listas (vetores) dos valores R, G e B para cada píxel:

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

Codificação de dados

As strings JSON têm de ser codificadas como UTF-8. Para enviar dados binários, tem de 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 seguinte mostra duas instâncias tf.Examples serializadas, que requerem codificação base64 (dados falsos, apenas para fins ilustrativos):

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

O exemplo seguinte mostra duas strings de bytes de imagens JPEG, que requerem a codificação base64 (dados falsos, apenas para fins ilustrativos):

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

Vários tensores de entrada

Alguns modelos têm um gráfico do TensorFlow subjacente que aceita vários tensores de entrada. Neste caso, use os nomes dos pares de chave-valor JSON para identificar os tensores de entrada.

Para um gráfico com aliases de tensores de entrada tag (string) e image (string codificada em base64):

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

Para um gráfico com aliases de tensores de entrada tag (string) e image (matriz tridimensional de números inteiros 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

Se o seu modelo usar um contentor pré-criado do PyTorch, os controladores predefinidos do TorchServe esperam que cada instância esteja incluída num campo data. Por exemplo:

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

Detalhes do corpo da resposta

Se a chamada for bem-sucedida, o corpo da resposta contém uma entrada de previsão por instância no corpo do pedido, apresentada na mesma ordem:

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

Se a previsão falhar para qualquer instância, o corpo da resposta não contém previsões. Em alternativa, contém uma única entrada de erro:

{
  "error": string
}

O objeto predictions[] contém a lista de previsões, uma para cada instância no pedido.

Em caso de erro, a string error contém uma mensagem que descreve o problema. O erro é devolvido em vez de uma lista de previsões se ocorrer um erro durante o processamento de qualquer instância.

Embora exista uma previsão por instância, o formato de uma previsão não está diretamente relacionado com o formato de uma instância. As previsões usam o formato especificado na coleção de saídas definida no modelo. A coleção de previsões é devolvida numa lista JSON. Cada membro da lista pode ser um valor, uma lista ou um objeto JSON de qualquer complexidade. Se o seu modelo tiver mais de um tensor de saída, cada previsão é um objeto JSON que contém um par de chave-valor para cada saída. As chaves identificam os alias de saída no gráfico.

Exemplos de corpos de respostas

Os exemplos seguintes mostram algumas respostas possíveis para o TensorFlow:

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

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

  • Um conjunto mais complexo de previsões, cada uma contendo dois valores com nomes que correspondem aos tensores de saída, denominados label e scores, respetivamente. O valor de label é a categoria prevista (car ou beach) e scores contém uma lista de probabilidades para essa instância nas possíveis categorias:

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

  • Uma resposta quando existe um erro ao processar uma instância de entrada:

    {"error": "Divide by zero"}