Fonction ML.PREDICT

Fonction ML.PREDICT

La fonction ML.PREDICT permet de prédire les résultats à l'aide du modèle. Vous pouvez effectuer des prédictions pendant la création du modèle, après la création du modèle ou en cas d'échec (à condition qu'au moins une itération soit terminée). La fonction ML.PREDICT utilise toujours les pondérations du modèle à partir de la dernière itération réussie.

Le résultat de la fonction ML.PREDICT affiche autant de lignes que la table d'entrée. Il inclut toutes les colonnes de la table d'entrée, ainsi que toutes les colonnes de résultat du modèle. Les noms de colonne de résultat du modèle sont predicted_<label_column_name> et predicted_<label_column_name>_probs (pour les modèles de régression logistique). Dans les deux colonnes, label_column_name est le nom de la colonne d'étiquette d'entrée utilisée lors de l'entraînement.

  • Pour les modèles de régression logistique :

    • La colonne de résultat predicted_<label_column_name>_probs est un tableau de structures de type [<label, prob>] qui contient la probabilité prédite de chaque étiquette.
    • La colonne de résultat predicted_<label_column_name> est l'une des deux étiquettes d'entrée, selon celle qui dispose de la probabilité prédite la plus élevée.
  • Pour les modèles de régression logistique multiclasses :

    • La colonne de résultat predicted_<label_column_name>_probs génère une probabilité pour chaque étiquette de classe calculée à l'aide d'une fonction softmax.
    • La colonne de résultat predicted_<label_column_name> est l'étiquette avec le score de probabilité prédite le plus élevé.
  • Pour les modèles de régression linéaire :

    • La colonne de résultat predicted_<label_column_name> correspond à la valeur prédite de l'étiquette.
  • Pour les modèles de k-moyennes :

    • Renvoie les colonnes avec les étiquettes centroid_id et nearest_centroids_distance. La colonne nearest_centroids_distance contient un tableau de structures nommé nearest_centroids_distance, qui affiche les distances des clusters k les plus proches, où k est égal au num_clusters le plus faible ou à 5. Si ce modèle a été créé avec l'option standardize_features définie sur TRUE, il calcule ces distances à l'aide de caractéristiques standardisées. Dans le cas contraire, le modèle calcule ces distances à l'aide de caractéristiques non standardisées.
  • Pour les modèles TensorFlow :

    • L'entrée doit être convertible pour correspondre au type attendu par le modèle.
    • Le résultat correspond à la sortie de la méthode "predict" du modèle TensorFlow.

Autorisations "ML.PREDICT"

Les autorisations bigquery.models.create et bigquery.models.getData sont toutes deux requises pour exécuter ML.PREDICT.

Syntaxe de ML.PREDICT

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

model_name

model_name est le nom du modèle que vous évaluez. Si aucun projet par défaut n'est configuré, ajoutez l'ID de projet au nom du modèle au format suivant : `[PROJECT_ID].[DATASET].[MODEL]` (en intégrant les accents graves), par exemple, `myproject.mydataset.mymodel`.

table_name

table_name est le nom de la table d'entrée qui contient les données d'évaluation. Si aucun projet par défaut n'est configuré, ajoutez l'ID de projet au nom de la table au format suivant : `[PROJECT_ID].[DATASET].[TABLE]` (en intégrant les accents graves), par exemple, `myproject.mydataset.mytable`.

Les noms des colonnes d'entrée de la table doivent contenir les noms des colonnes du modèle, et leurs types doivent être compatibles suivant les règles de coercition implicites de BigQuery.

Si la table génère des colonnes inutilisées, celles-ci sont transmises aux colonnes de résultat.

query_statement

La clause query_statement spécifie en langage SQL standard la requête permettant de générer les données d'évaluation. Reportez-vous à la page Syntaxe des requêtes en SQL standard pour connaître la syntaxe SQL compatible avec la clause query_statement.

Les noms des colonnes d'entrée de la requête doivent contenir les noms des colonnes du modèle, et leurs types doivent être compatibles suivant les règles de coercition implicites de BigQuery.

Si la requête génère des colonnes inutilisées, celles-ci sont transmises aux colonnes de résultat.

Si la clause TRANSFORM était présente dans l'instruction CREATE MODEL qui a créé model_name, seules les colonnes d'entrée présentes dans la clause TRANSFORM doivent apparaître dans query_statement.

threshold

(Facultatif) Le seuil (threshold) est un seuil personnalisé pour votre modèle de régression logistique binaire et sert de limite entre les deux étiquettes. Les prédictions au-dessus du seuil sont identifiées comme positives. Les prédictions en dessous du seuil sont considérées comme négatives. La valeur du seuil est de type FLOAT64 et fait partie des paramètres STRUCT. La valeur par défaut est 0,5.

Imputation

Dans le domaine statistique, l'imputation permet de remplacer des données manquantes par des valeurs. Lorsque vous entraînez un modèle dans BigQuery ML, les valeurs NULL sont considérées comme des données manquantes. Lorsque vous effectuez des prédictions dans BigQuery ML, vous pouvez vous heurter à des valeurs manquantes lorsque BigQuery ML rencontre une valeur NULL ou une valeur non répertoriée. BigQuery ML gère les données manquantes différemment, selon si celles-ci se trouvent dans une colonne numérique, une colonne à encodage one-hot ou une colonne d'horodatage.

Colonnes numériques

Lors des opérations d'entraînement et de prédiction, les valeurs NULL des colonnes numériques sont remplacées par la valeur moyenne calculée par la colonne de caractéristiques dans les données d'entrée d'origine.

Colonnes à encodage one-hot/multi-hot

Lors des opérations d'entraînement et de prédiction, les valeurs NULL des colonnes à encodage one-hot ou multi-hot sont mappées vers une catégorie supplémentaire, qui est ajoutée aux données. Une pondération de 0 est attribuée aux données non répertoriées lors de la prédiction.

Colonnes d'horodatage

Les colonnes d'horodatage (TIMESTAMP) ont recours à un mélange des méthodes d'imputation utilisées pour les colonnes standardisées et les colonnes à encodage one-hot. Pour la colonne de temps Unix générée, BigQuery ML remplace les valeurs par le temps Unix moyen des colonnes d'origine. BigQuery ML attribue le reste des valeurs générées à la catégorie NULL respective pour chacune des caractéristiques extraites.

Colonnes STRUCT

Lors des opérations d'entraînement et de prédiction, chaque champ de colonne STRUCT est imputé en fonction de son type.

Exemples d'instructions ML.PREDICT

Dans les exemples suivants, nous supposons que le modèle et la table d'entrée se trouvent dans le projet par défaut.

Prédire un résultat

La requête suivante utilise la fonction ML.PREDICT pour prédire des résultats. La requête renvoie les colonnes suivantes :

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

Comparer les prédictions de deux modèles différents

Dans cet exemple, la requête ci-dessous crée le premier modèle.

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

La requête suivante crée le deuxième modèle.

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

La requête suivante utilise la fonction ML.PREDICT pour comparer les résultats des deux modèles.

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`)))

Spécifier un seuil personnalisé

La requête suivante utilise la fonction ML.PREDICT en spécifiant des données d'entrée, ainsi qu'un seuil personnalisé de 0.55.

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

Prédire un résultat avec un modèle TensorFlow importé

La requête suivante utilise la fonction ML.PREDICT pour prédire des résultats à l'aide d'un modèle TensorFlow importé. La table input_data contient des données d'entrée du schéma attendu par my_model. Consultez la section Instruction CREATE MODEL pour importer des modèles TensorFlow pour en savoir plus.

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

Prédire un résultat avec un modèle entraîné à l'aide de la clause TRANSFORM

La requête suivante entraîne un modèle à l'aide de la clause TRANSFORM.

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

Comme la colonne f3 n'apparaît pas dans la clause TRANSFORM, la requête de prédiction suivante omet cette colonne dans le champ query_statement :

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

Si la colonne f3 est fournie dans l'instruction SELECT, elle n'est pas utilisée pour le calcul des prédictions. Elle est toutefois transmise pour être utilisée dans le reste de l'instruction SQL.