Receber previsões de um modelo de previsão

A Vertex AI oferece duas opções para projetar valores futuros usando seu modelo de previsão treinado: previsões on-line e em lote.

Uma previsão on-line é uma solicitação síncrona. Use predições on-line ao fazer solicitações em resposta à entrada do aplicativo ou em outras situações em que você precisa de inferência em tempo hábil.

Uma solicitação de previsão em lote é assíncrona. Use as previsões em lote quando não precisar de uma resposta imediata e quiser processar dados acumulados com uma única solicitação.

Nesta página, mostramos como projetar valores futuros usando previsões on-line. Para saber como projetar valores usando previsões em lote, consulte Receber previsões em lote para um modelo de previsão.

É preciso implantar seu modelo em um endpoint antes de usá-lo para previsões. Um endpoint é um conjunto de recursos físicos.

É possível solicitar uma explicação em vez de uma previsão. Os valores de importância do recurso local da explicação informam quanto cada recurso contribuiu para o resultado da previsão. Para uma visão geral conceitual, consulte Atribuições de recursos para previsão.

Para saber mais sobre os preços das previsões on-line, consulte Preços para fluxos de trabalho tabulares.

Antes de começar

Antes de fazer uma solicitação de previsão on-line, é necessário treinar um modelo.

Criar ou selecionar um endpoint

Use a função aiplatform.Endpoint.create() para criar um endpoint. Se você já tiver um endpoint, use a função aiplatform.Endpoint() para selecioná-lo.

O código a seguir mostra um exemplo:

# Import required modules
from google.cloud import aiplatform
from google.cloud.aiplatform import models

PROJECT_ID = "PROJECT_ID"
REGION = "REGION"

# Initialize the Vertex SDK for Python for your project.
aiplatform.init(project=PROJECT_ID, location=REGION)
endpoint = aiplatform.Endpoint.create(display_name='ENDPOINT_NAME')

Substitua:

  • PROJECT_ID: o ID do projeto.
  • REGION: a região em que você está usando a Vertex AI.
  • ENDPOINT_NAME: nome de exibição do endpoint.

Selecione um modelo treinado

Use a função aiplatform.Model() para selecionar um modelo treinado:

# Create reference to the model trained ahead of time.
model_obj = models.Model("TRAINED_MODEL_PATH")

Substitua:

  • TRAINED_MODEL_PATH: Por exemplo, projects/PROJECT_ID/locations/REGION/models/[TRAINED_MODEL_ID]

Implante o modelo no endpoint

Use a função deploy() para implantar o modelo no endpoint. O código a seguir mostra um exemplo:

deployed_model = endpoint.deploy(
    model_obj,
    machine_type='MACHINE_TYPE',
    traffic_percentage=100,
    min_replica_count='MIN_REPLICA_COUNT',
    max_replica_count='MAX_REPLICA_COUNT',
    sync=True,
    deployed_model_display_name='DEPLOYED_MODEL_NAME',
)

Substitua:

  • MACHINE_TYPE: por exemplo, n1-standard-8. Saiba mais sobre tipos de máquinas.
  • MIN_REPLICA_COUNT: o número mínimo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de previsão, até o número máximo de nós e nunca menos que esse número. O valor precisa ser maior ou igual a 1. Se a variável min_replica_count não estiver definida, o valor padrão será 1.
  • MAX_REPLICA_COUNT: o número máximo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de previsão, até esse número de nós e nunca menos que o número mínimo de nós. Se você não definir a variável max_replica_count, o número máximo de nós será definido como o valor de min_replica_count.
  • DEPLOYED_MODEL_NAME: um nome para DeployedModel. Também é possível usar o nome de exibição do Model para o DeployedModel.

A implantação de modelos pode levar cerca de dez minutos.

Receber previsões on-line

Para receber previsões, use a função predict() e forneça uma ou mais instâncias de entrada. O código a seguir mostra um exemplo:

predictions = endpoint.predict(instances=[{...}, {...}])

Cada instância de entrada é um dicionário Python com o mesmo esquema em que o modelo foi treinado. Ela precisa conter um par de chave-valor disponível na previsão que corresponda à coluna de tempo e um par de chave-valor indisponível na previsão que contenha o valor histórico. valores da coluna de previsão segmentada. A Vertex AI espera que cada instância de entrada pertença a uma única série temporal. A ordem dos pares de chave-valor na instância não é importante.

A entrada está sujeita às restrições a seguir:

  • Os pares de chave-valor disponíveis na previsão precisam ter o mesmo número de pontos de dados.
  • Os pares de chave-valor indisponível na previsão precisam ter o mesmo número de pontos de dados.
  • Os pares de chave-valor disponíveis na previsão precisam ter pelo menos tantos pontos de dados quanto os pares de chave-valor indisponível na previsão.

Para saber mais sobre os tipos de colunas usados na previsão, consulte Tipo de recurso e disponibilidade na previsão.

O código a seguir demonstra um conjunto de duas instâncias de entrada. A coluna Category contém dados de atributos. A coluna Timestamp contém dados disponíveis na previsão. Três pontos são dados de contexto e dois pontos são dados do horizon. A coluna Sales contém dados que não estão disponíveis na previsão. Todos os três pontos são dados de contexto. Para saber como o contexto e o horizonte são usados na previsão, consulte Outono da previsão, janela de contexto e janela de previsão.

instances=[
  {
    # Attribute
    "Category": "Electronics",
    # Available at forecast: three days of context, two days of horizon
    "Timestamp": ['2023-08-03', '2023-08-04', '2023-08-05', '2023-08-06', '2023-08-07'],
    # Unavailable at forecast: three days of context
    "Sales": [490.50, 325.25, 647.00],
  },
  {
    # Attribute
    "Category": "Food",
    # Available at forecast: three days of context, two days of horizon
    "Timestamp": ['2023-08-03', '2023-08-04', '2023-08-05', '2023-08-06', '2023-08-07'],
    # Unavailable at forecast: three days of context
    "Sales": [190.50, 395.25, 47.00],
  }
])

Para cada instância, a Vertex AI responde com duas previsões para Sales, correspondentes aos dois carimbos de data/hora do horizon ("2023-08-06" e "2023-08-07").

Para um desempenho ideal, o número de pontos de dados de contexto e o número de pontos de dados de horizonte em cada instância de entrada precisam corresponder ao comprimento do contexto e do horizonte foi treinado. Se houver uma incompatibilidade, a Vertex AI preenche ou trunca a instância para corresponder ao tamanho do modelo.

Se o número de pontos de dados de contexto na instância de entrada for menor ou maior que o número de pontos de dados de contexto usados para o treinamento do modelo, verifique se esse número de pontos é consistente em todos os pares de chave-valor disponíveis na previsão e todos os pares de chave-valor indisponíveis na previsão.

Por exemplo, considere um modelo treinado com quatro dias de dados de contexto e dois dias de dados de horizon. É possível fazer uma solicitação de previsão com apenas três dias de dados de contexto. Nesse caso, os pares de chave-valor indisponível na previsão contêm três valores. Os pares de chave-valor disponíveis na previsão precisam conter cinco valores.

Saída da previsão on-line

A Vertex AI fornece saída de previsão on-line no campo value:

{
  'value': [...]
}

O comprimento da resposta de previsão depende do horizonte usado no treinamento do modelo e do horizonte da instância de entrada. O comprimento da resposta de previsão é o menor desses dois valores.

Confira estes exemplos:

  • Você treina um modelo com context = 15 e horizon = 50. A instância de entrada tem context = 15 e horizon = 20. A resposta da previsão tem um comprimento de 20.
  • Você treina um modelo com context = 15 e horizon = 50. A instância de entrada tem context = 15 e horizon = 100. A resposta da previsão tem um comprimento de 50.

Saída de previsão on-line para modelos TFT

Para modelos treinados com o Transformador de fusão temporal (TFT, na sigla em inglês), a Vertex AI fornece interpretabilidade de TFT tft_feature_importance, além de previsões no campo value:

{
  "tft_feature_importance": {
    "attribute_weights": [...],
    "attribute_columns": [...],
    "context_columns": [...],
    "context_weights": [...],
    "horizon_weights": [...],
    "horizon_columns": [...]
  },
  "value": [...]
}
  • attribute_columns: recursos de previsão que são invariantes ao tempo.
  • attribute_weights: os pesos associados a cada uma das attribute_columns.
  • context_columns: recursos de previsão com valores de janela de contexto que servem como entradas para o codificador de memória de curto prazo longa (LSTM, na sigla em inglês) do TFT.
  • context_weights: os pesos de importância do atributo associados a cada um dos context_columns para a instância prevista.
  • horizon_columns: atributos de previsão com valores de horizonte de previsão que servem como entradas para o decodificador de memória de curto prazo longa (LSTM, na sigla em inglês) do TFT.
  • horizon_weights: os pesos de importância do atributo associados a cada um dos horizon_columns para a instância prevista.

Saída de previsão on-line para modelos otimizados para perda de quantis

Para modelos otimizados para perda de quantil, a Vertex AI fornece a seguinte saída de previsão on-line:

{
  "value": [...],
  "quantile_values": [...],
  "quantile_predictions": [...]
}
  • value: se o conjunto de quantis incluir a mediana, value será o valor da previsão na mediana. Caso contrário, value é o valor de previsão no quantil mais baixo do conjunto. Por exemplo, se o conjunto de quantis for [0.1, 0.5, 0.9], value será a previsão para o quantil 0.5. Se o conjunto de quantis for [0.1, 0.9], value será a previsão para o quantil 0.1.
  • quantile_values: os valores dos quantis, que são definidos durante o treinamento do modelo.
  • quantile_predictions: os valores de previsão associados aos quantile_values.

Considere, por exemplo, um modelo em que a coluna de destino é o valor de vendas. Os valores de quantis são definidos como [0.1, 0.5, 0.9]. A Vertex AI retorna as seguintes previsões de quantil: [4484, 5615, 6853]. Aqui, o conjunto de quantis inclui a mediana. Portanto, value é a previsão para o quantil 0.5 (5615). As previsões de quantis podem ser interpretadas da seguinte maneira:

  • P(valor de vendas < 4.484) = 10%
  • P(valor de vendas < 5.615) = 50%
  • P(valor de vendas < 6.853) = 90%

Saída de previsão on-line para modelos com inferência probabilística

Se o modelo usar a inferência probabilística, o campo value vai conter o minimizador do objetivo de otimização. Por exemplo, se o objetivo de otimização for minimize-rmse, o campo value conterá o valor médio. Se for minimize-mae, o campo value conterá o valor mediano.

Se o modelo usa inferência probabilística com quantis, a Vertex AI fornece valores e previsões de quantis, além de minimizar o objetivo de otimização. Os valores de quantis são definidos durante o treinamento do modelo. As previsões de quantis são os valores de previsão associados aos valores de quantis.

Ver explicações on-line

Para ver explicações, use a função explain() e forneça uma ou mais instâncias de entrada. O código a seguir mostra um exemplo:

explanations = endpoint.explain(instances=[{...}, {...}])

O formato das instâncias de entrada é o mesmo para previsões e explicações on-line. Para saber mais, consulte Receber previsões on-line.

Para uma visão geral conceitual das atribuições de recursos, consulte Atribuições de recursos para previsão.

Saída da explicação on-line

O código a seguir demonstra como gerar os resultados da explicação:

# Import required modules
import json
from google.protobuf import json_format

def explanation_to_dict(explanation):
  """Converts the explanation proto to a human-friendly json."""
  return json.loads(json_format.MessageToJson(explanation._pb))

for response in explanations.explanations:
  print(explanation_to_dict(response))

Os resultados das explicações têm o seguinte formato:

{
  "attributions": [
    {
      "baselineOutputValue": 1.4194682836532593,
      "instanceOutputValue": 2.152980089187622,
      "featureAttributions": {
        ...
        "store_id": [
          0.007947325706481934
        ],
        ...
        "dept_id": [
          5.960464477539062e-08
        ],
        "item_id": [
          0.1100526452064514
        ],
        "date": [
          0.8525647521018982
        ],
        ...
        "sales": [
          0.0
        ]
      },
      "outputIndex": [
        2
      ],
      "approximationError": 0.01433318599207033,
      "outputName": "value"
    },
    ...
  ]
}

O número de elementos attributions depende do horizonte usado no treinamento do modelo e do horizonte da instância de entrada. O número de elementos é o menor desses dois valores.

O campo featureAttributions em um elemento attributions contém um valor para cada uma das colunas no conjunto de dados de entrada. A Vertex AI gera explicações para todos os tipos de recursos: atributo, disponível na previsão e indisponível na previsão. Para saber mais sobre os campos de um elemento attributions, consulte Atribuição.

Exclua o endpoint

Use as funções undeploy_all() e delete() para excluir o endpoint. O código a seguir mostra um exemplo:

endpoint.undeploy_all()
endpoint.delete()

A seguir