Formatar suas solicitações de previsão

Use as previsões on-line ao fazer solicitações em resposta a uma entrada de aplicativo ou em situações que exigem inferência em tempo hábil (respostas em tempo real).

Nesta página, mostramos como formatar solicitações de previsão on-line usando a API Online Prediction para seus modelos treinados personalizados e fornecemos exemplos de solicitações e respostas. Depois de formatar sua solicitação, você pode receber uma previsão on-line.

Antes de começar

Antes de formatar uma solicitação para fazer previsões on-line, siga estas etapas:

1. Exporte o artefato do modelo para previsão.

2. Implante o recurso de modelo em um endpoint.

   Essa ação associa recursos de computação ao modelo para que ele possa fazer previsões on-line com baixa latência.

3. Verifique o status do recurso personalizado DeployedModel do seu modelo e confirme se ele está pronto para aceitar solicitações de previsão:

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

   Substitua:

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

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

   A saída a seguir mostra um exemplo de resposta:

   {"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 status do recurso personalizado Endpoint e confira se ele está pronto para aceitar solicitações de previsão:

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

   Substitua:

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

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

   A saída a seguir mostra um exemplo de resposta:

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

Formatar a entrada para previsões on-line

A previsão on-line tem dois métodos para enviar solicitações:

• Solicitação de previsão: envie uma solicitação para o método predict para receber uma previsão on-line.
• Solicitação de previsão bruta: envie uma solicitação para o método rawPredict, que permite usar um payload HTTP arbitrário em vez de seguir um formato JSON.

Se você precisar de baixa latência, receba previsões brutas porque rawPredict ignora as etapas de serialização e encaminha diretamente a solicitação para o contêiner de previsão.

Nesta seção, mostramos como formatar e codificar suas instâncias de entrada de previsão usando JSON, o que é necessário se você estiver usando o método predict. Essas informações não são necessárias se você estiver usando o método rawPredict.

Se você estiver usando o SDK da Vertex AI para Python para enviar solicitações 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"], ... ] }.

Formatar instâncias como strings JSON

O formato básico da previsão on-line é uma lista de instâncias de dados. Ela pode ser uma lista simples de valores ou membros de um objeto JSON, dependendo de como você configurou as entradas no aplicativo de treinamento. Os modelos do TensorFlow podem aceitar entradas mais complexas.

O exemplo a seguir 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, contanto que siga estas regras:

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

• Os valores individuais em um objeto de instância podem ser strings, números ou listas. Não é possível incorporar objetos JSON.

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

Transmita as instâncias de entrada para previsão on-line como o corpo da mensagem da chamada predict. Saiba mais sobre os requisitos de formatação do corpo da solicitação.

Torne cada instância um item em uma matriz JSON e forneça a matriz como o campo instances de um objeto JSON, como no exemplo a seguir:

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

Codificar dados binários para entrada de previsão

Não é possível formatar dados binários como as strings codificadas em UTF-8 compatíveis com JSON. Se houver dados binários nas entradas, use a codificação base64 para representá-los. Você precisa da seguinte formatação especial:

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

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

• No código do modelo do TensorFlow, nomeie os aliases dos seus tensores binários de entrada e saída para que terminem com _bytes.

Exemplos de solicitação e resposta

Nesta seção, descrevemos o formato dos corpos da solicitação e da resposta de previsão on-line com exemplos para TensorFlow e PyTorch.

Detalhes do corpo da solicitação

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

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

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

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

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

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

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

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

{"b64": "..."}

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

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

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

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

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

Detalhes do corpo da resposta

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
    }
  ],
  "deployedModelId": string
}

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.

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, uma lista ou um objeto JSON de qualquer complexidade. Se o seu modelo tiver mais de um tensor de saída, cada previsão será um objeto JSON com um par de chave-valor para cada saída. As chaves identificam os aliases de saída no gráfico.

Exemplos de corpo de resposta

Confira alguns exemplos de respostas possíveis para o TensorFlow:

• Conjunto de previsões de 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 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]
      }
    ],
    "deployedModelId": 123456789012345678
  }
  

• Resposta quando há um erro ao processar uma instância de entrada:

  {"error": "Divide by zero"}