Função ML.PREDICT

Função ML.PREDICT

A função ML.PREDICT pode ser usada para prever resultados usando o modelo. A previsão pode ser feita durante ou após a criação do modelo ou, ainda, depois de uma falha, desde que pelo menos uma iteração tenha terminado. ML.PREDICT sempre usa os pesos de modelo da última iteração bem-sucedida.

A saída da função ML.PREDICT tem tantas linhas quanto a tabela de entrada e inclui todas as colunas da tabela de entrada e todas as colunas de saída do modelo. Os nomes das colunas de saída para o modelo são predicted_<label_column_name> e (para modelos de regressão logística) predicted_<label_column_name>_probs. Nas duas colunas, label_column_name é o nome da coluna do rótulo de entrada usada durante o treinamento.

  • Para modelos de regressão logística:

    • A coluna de saída predicted_<label_column_name>_probs é uma matriz de STRUCTs do tipo [<label, prob>] que contém a probabilidade prevista de cada rótulo.
    • A coluna de saída predicted_<label_column_name> é um dos dois rótulos de entrada, dependendo de qual rótulo tem a maior probabilidade prevista.
  • Para modelos de regressão logística multiclasse:

    • A coluna de saída predicted_<label_column_name>_probs é a probabilidade de cada rótulo de classe calculado por meio de uma função softmax.
    • A coluna de saída predicted_<label_column_name> é o rótulo com a maior pontuação de probabilidade prevista.
  • Para modelos de regressão linear:

    • A coluna de saída predicted_<label_column_name> é o valor previsto do rótulo.
  • Para modelos k-means:

    • Retorna colunas com os rótulos centroid_id e nearest_centroids_distance. nearest_centroids_distance contém um ARRAY de STRUCTs denominado nearest_centroids_distance, que contém as distâncias dos clusters k mais próximos, em que k é igual ao menor valor de num_clusters ou 5. Se este modelo tiver sido criado com a opção standardize_features definida como TRUE, o modelo calculará essas distâncias usando recursos padronizados. Caso contrário, o cálculo considerará recursos não padronizados.
  • Para modelos do TensorFlow:

    • A entrada precisa ser conversível no tipo esperado pelo modelo.
    • A saída é a saída do método de previsão do modelo do TensorFlow.

Sintaxe ML.PREDICT

ML.PREDICT(MODEL model_name,
          {TABLE table_name | (query_statement)}
          [, STRUCT<threshold FLOAT64> settings)])

model_name

model_name é o nome do modelo que você está avaliando. Na falta de um projeto padrão configurado, adicione o ID do projeto ao nome do modelo no seguinte formato: `[PROJECT_ID].[DATASET].[MODEL]` (incluindo os acentos graves); por exemplo, `myproject.mydataset.mymodel`.

table_name

table_name é o nome da tabela de entrada que contém os dados de avaliação. Na falta de um projeto padrão configurado, adicione o ID do projeto ao nome da tabela no seguinte formato: `[PROJECT_ID].[DATASET].[TABLE]` (incluindo os acentos graves); por exemplo, `myproject.mydataset.mytable`.

Os nomes das colunas de entrada da tabela precisam conter os nomes das colunas do modelo e seus tipos precisam ser compatíveis de acordo com as regras implícitas de coerção do BigQuery.

Se houver colunas sem uso na tabela, elas serão passadas para as colunas de saída.

query_statement

A cláusula query_statement especifica a consulta do SQL padrão usada para gerar os dados de avaliação. Para saber qual a sintaxe SQL compatível com a cláusula query_statement, consulte a página Sintaxe de consulta do SQL padrão.

Os nomes das colunas de entrada da consulta precisam conter os nomes das colunas do modelo e seus tipos precisam ser compatíveis de acordo com as regras implícitas de coerção do BigQuery.

Se houver colunas sem uso na consulta, elas serão passadas para as colunas de saída.

Se a cláusula TRANSFORM estava presente na instrução CREATE MODEL que criou model_name, somente as colunas de entrada presentes na cláusula TRANSFORM devem aparecer em query_statement.

threshold

(Opcional) É um limite personalizado do modelo de regressão logística binária, usado como limite entre os dois rótulos. As predições acima do limite são tratadas como positivas. As predições abaixo do limite são negativas. O valor limite é do tipo FLOAT64 e faz parte das configurações STRUCT. O valor padrão é 0,5.

Imputação

Em estatística, a imputação é usada para substituir dados ausentes por valores substitutos. Quando você treina um modelo no BigQuery ML, os valores NULL são tratados como dados ausentes. Quando você prevê resultados no BigQuery ML, podem ocorrer valores ausentes quando o BigQuery ML encontra um valor NULL ou um valor não visto anteriormente. O BigQuery ML manipula dados ausentes com base no tipo da coluna: numérica, codificação one-hot ou carimbo de data/hora.

Colunas numéricas

No treinamento e na predição, os valores NULL em colunas numéricas são substituídos pelo valor médio, conforme calculado pela coluna de recurso nos dados de entrada originais.

Colunas de codificação one-hot/multi-hot

Seja no treinamento ou na predição, os valores NULL nas colunas de codificação são mapeados para uma categoria extra que é adicionada aos dados. Os dados não vistos anteriormente recebem peso 0 durante a predição.

Colunas de carimbo de data/hora

Colunas TIMESTAMP usam uma combinação de métodos de imputação de colunas padronizadas e de codificação one-hot. Para a coluna de tempo do unix gerada, o BigQuery ML substitui os valores pelo tempo médio do unix das colunas originais. Para os outros valores gerados, o BigQuery ML os atribui à respectiva categoria NULL de cada recurso extraído.

Colunas STRUCT

Tanto no treinamento quanto na previsão, cada campo de STRUCT é imputado de acordo com seu tipo.

Exemplos de ML.PREDICT

Nos exemplos a seguir, pressupomos que o modelo e a tabela de entrada estão no projeto padrão.

Como prever um resultado

A consulta a seguir usa a função ML.PREDICT para prever um resultado. A consulta retorna essas colunas:

  • predicted_label
  • label
  • column1
  • column2
SELECT
  *
FROM
  ML.PREDICT(MODEL `mydataset.mymodel`,
    (
    SELECT
      label,
      column1,
      column2
    FROM
      `mydataset.mytable`))

Como comparar previsões de dois modelos diferentes

Neste exemplo, usamos a consulta a seguir para criar o primeiro modelo.

CREATE MODEL
  `mydataset.mymodel1`
OPTIONS
  (model_type='linear_reg',
    input_label_cols=['label'],
  ) AS
SELECT
  label,
  input_column1
FROM
  `mydataset.mytable`

A consulta a seguir é usada para criar o segundo modelo.

CREATE MODEL
  `mydataset.mymodel2`
OPTIONS
  (model_type='linear_reg',
    input_label_cols=['label'],
  ) AS
SELECT
  label,
  input_column2
FROM
  `mydataset.mytable`

A consulta a seguir usa a função ML.PREDICT para comparar a saída dos dois modelos.

SELECT
  label,
  predicted_label1,
  predicted_label AS predicted_label2
FROM
  ML.PREDICT(MODEL `mydataset.mymodel2`,
    (
    SELECT
      * EXCEPT (predicted_label),
          predicted_label AS predicted_label1
    FROM
      ML.PREDICT(MODEL `mydataset.mymodel1`,
        TABLE `mydataset.mytable`)))

Como especificar um limite personalizado

A consulta a seguir usa a função ML.PREDICT especificando dados de entrada e um limite personalizado de 0.55.

SELECT
  *
FROM
  ML.PREDICT(MODEL `mydataset.mymodel`,
    (
    SELECT
      custom_label,
      column1,
      column2
    FROM
      `mydataset.mytable`),
    STRUCT(0.55 AS threshold))

Como prever um resultado com um modelo importado do TensorFlow

A consulta a seguir usa a função ML.PREDICT para prever resultados usando um modelo importado do TensorFlow. A tabela input_data contém entradas no esquema esperado por my_model. Para mais informações, consulte a instrução CREATE MODEL para modelos do TensorFlow.

SELECT *
FROM ML.PREDICT(MODEL `my_project`.my_dataset.my_model,
               (SELECT * FROM input_data))

Como prever um resultado com um modelo treinado com a cláusula TRANSFORM

A consulta a seguir treina um modelo usando a cláusula TRANSFORM:

CREATE MODEL m
  TRANSFORM(f1 + f2 as c, label)
  OPTIONS(...)
AS SELECT f1, f2, f3, label FROM t;

Como a coluna f3 não aparece na cláusula TRANSFORM, a seguinte consulta de previsão omite essa coluna em query_statement:

SELECT * FROM ML.PREDICT(
  MODEL m, (SELECT f1, f2 FROM t1));

Se f3 for fornecido na instrução SELECT, ele não será usado para calcular previsões, mas será transmitido para uso no restante da instrução SQL.