Exporter des modèles

Présentation

Cette page explique comment exporter des modèles BigQuery ML. Vous pouvez exporter des modèles BigQuery ML vers Cloud Storage et les utiliser pour la prédiction en ligne, ou les modifier en langage Python. Vous pouvez exporter un modèle BigQuery ML à l'aide des méthodes suivantes :

• Utiliser la console Google Cloud.
• Utiliser l'instruction EXPORT MODEL.
• En utilisant la commande bq extract de l'outil de ligne de commande bq.
• En envoyant une tâche extract via l'API ou les bibliothèques clientes

Vous pouvez exporter les types de modèles suivants :

• AUTOENCODER
• AUTOML_CLASSIFIER
• AUTOML_REGRESSOR
• BOOSTED_TREE_CLASSIFIER
• BOOSTED_TREE_REGRESSOR
• DNN_CLASSIFIER
• DNN_REGRESSOR
• DNN_LINEAR_COMBINED_CLASSIFIER
• DNN_LINEAR_COMBINED_REGRESSOR
• KMEANS
• LINEAR_REG
• LOGISTIC_REG
• MATRIX_FACTORIZATION
• RANDOM_FOREST_CLASSIFIER
• RANDOM_FOREST_REGRESSOR
• TENSORFLOW (modèles TensorFlow importés)
• PCA
• TRANSFORM_ONLY

Formats et exemples de modèles d'exportation

Le tableau suivant présente les formats de destination des exportations pour chaque type de modèle BigQuery ML et fournit un exemple des fichiers écrits dans le bucket Cloud Storage.

Exporter un modèle entraîné avec TRANSFORM

Si le modèle est entraîné avec la clause TRANSFORM, un modèle de prétraitement supplémentaire utilise la même logique dans la clause TRANSFORM et est enregistré au format TensorFlow SavedModel dans le sous-répertoire transform. Vous pouvez déployer un modèle entraîné avec la clause TRANSFORM sur Vertex AI ainsi qu'en local. Pour en savoir plus, consultez la section Déploiement de modèle.

Le modèle ne contient pas d'informations sur le développement fonctionnel mis en œuvre en dehors de la clause TRANSFORM pendant l'entraînement. Par exemple, tout ce qui est dans l'instruction SELECT. Vous devez donc convertir manuellement les données d'entrée avant de les utiliser dans le modèle de prétraitement.

Types de données acceptés

Lors de l'exportation de modèles entraînés avec la clause TRANSFORM, les types de données suivants sont compatibles pour alimenter la clause TRANSFORM.

Fonctions SQL compatibles

Lorsque vous exportez des modèles entraînés avec la clause TRANSFORM, vous pouvez utiliser les fonctions SQL suivantes dans la clause TRANSFORM.

• Opérateurs
  • +, -, *, /, =, <, >, <=, >=, !=, <>, [NOT] BETWEEN, [NOT] IN, IS [NOT] NULL, IS [NOT] TRUE, IS [NOT] FALSE, NOT, AND, OR.
• Expressions conditionnelles
  • CASE expr, CASE, COALESCE, IF, IFNULL, NULLIF.
• Fonctions mathématiques
  • ABS, ACOS, ACOSH, ASINH, ATAN, ATAN2, ATANH, CBRT, CEIL, CEILING, COS, COSH, COT, COTH, CSC, CSCH, EXP, FLOOR, IS_INF, IS_NAN, LN, LOG, LOG10, MOD, POW, POWER, SEC, SECH, SIGN, SIN, SINH, SQRT, TAN, TANH.
• Fonctions de conversion
  • CAST AS INT64, CAST AS FLOAT64, CAST AS NUMERIC, CAST AS BIGNUMERIC, CAST AS STRING, SAFE_CAST AS INT64, SAFE_CAST AS FLOAT64
• Fonctions de chaîne
  • CONCAT, LEFT, LENGTH, LOWER, REGEXP_REPLACE, RIGHT, SPLIT, SUBSTR, SUBSTRING, TRIM, UPPER.
• Fonctions de date
  • Date, DATE_ADD, DATE_SUB, DATE_DIFF, DATE_TRUNC, EXTRACT, FORMAT_DATE, PARSE_DATE, SAFE.PARSE_DATE.
• Fonctions DATETIME
  • DATETIME, DATETIME_ADD, DATETIME_SUB, DATETIME_DIFF, DATETIME_TRUNC, EXTRACT, PARSE_DATETIME, SAFE.PARSE_DATETIME.
• Fonctions TIME
  • TIME, TIME_ADD, TIME_SUB, TIME_DIFF, TIME_TRUNC, EXTRACT, FORMAT_TIME, PARSE_TIME, SAFE.PARSE_TIME.
• Fonctions TIMESTAMP
  • TIMESTAMP, TIMESTAMP_ADD, TIMESTAMP_SUB, TIMESTAMP_DIFF, TIMESTAMP_TRUNC, FORMAT_TIMESTAMP, PARSE_TIMESTAMP, SAFE.PARSE_TIMESTAMP, TIMESTAMP_MICROS, TIMESTAMP_MILLIS, TIMESTAMP_SECONDS, EXTRACT, STRING, UNIX_MICROS, UNIX_MILLIS, UNIX_SECONDS.
• Fonctions de prétraitement manuel
  • ML.IMPUTER, ML.HASH_BUCKETIZE, ML.LABEL_ENCODER, ML.MULTI_HOT_ENCODER, ML.NGRAMS, ML.ONE_HOT_ENCODER, ML.BUCKETIZE, ML.MAX_ABS_SCALER, ML.MIN_MAX_SCALER, ML.NORMALIZER, ML.QUANTILE_BUCKETIZE, ML.ROBUST_SCALER, ML.STANDARD_SCALER.

Limites

Les limites suivantes s'appliquent lors de l'exportation de modèles :

• L'exportation du modèle n'est pas possible si l'une des caractéristiques suivantes a été utilisée pendant l'entraînement :

  • Les types caractéristiques ARRAY, TIMESTAMP ou GEOGRAPHY étaient présents dans les données d'entrée.

• Les modèles exportés pour les types de modèle AUTOML_REGRESSOR et AUTOML_CLASSIFIER ne sont pas compatibles avec le déploiement de Vertex AI pour la prédiction en ligne.

• Pour l'exportation du modèle de factorisation matricielle, la taille du modèle est limitée à 1 Go. La taille du modèle est approximativement proportionnelle à num_factors. Si la limite est atteinte, vous pouvez donc réduire la valeur de num_factors pendant l'entraînement de façon à réduire la taille du modèle.

• Pour les modèles entraînés avec la clause TRANSFORM BigQuery ML pour le prétraitement manuel des caractéristiques, consultez les types de données et fonctions compatibles avec l'exportation.

• Les modèles entraînés avec la clause BigQuery MLTRANSFORM avant le 18 septembre 2023 doivent être réentraînés pour pouvoir être déployés via Model Registry pour la prédiction en ligne.

• Lors de l'exportation du modèle, ARRAY<STRUCT<INT64, FLOAT64>>, ARRAY et TIMESTAMP sont acceptés en tant que données prétransformées, mais pas en tant que données post-transformées.

Exporter des modèles BigQuery ML

Pour exporter un modèle, procédez comme suit :

bq --location=location extract \
--destination_format format \
--model project_id:dataset.model \
gs://bucket/model_folder

bq extract --model \
'mydataset.mymodel' \
gs://example-bucket/mymodel_folder

bq extract --model \
--destination_format ML_XGBOOST_BOOSTER \
'mydataset.mytable' \
gs://example-bucket/mymodel_folder

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.ExtractJobConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.ModelId;

// Sample to extract model to GCS bucket
public class ExtractModel {

  public static void main(String[] args) throws InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    String projectName = "bigquery-public-data";
    String datasetName = "samples";
    String modelName = "model";
    String bucketName = "MY-BUCKET-NAME";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    extractModel(projectName, datasetName, modelName, destinationUri);
  }

  public static void extractModel(
      String projectName, String datasetName, String modelName, String destinationUri)
      throws InterruptedException {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      ModelId modelId = ModelId.of(projectName, datasetName, modelName);

      ExtractJobConfiguration extractConfig =
          ExtractJobConfiguration.newBuilder(modelId, destinationUri).build();

      Job job = bigquery.create(JobInfo.of(extractConfig));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Model extract successful");
    } catch (BigQueryException ex) {
      System.out.println("Model extraction job was interrupted. \n" + ex.toString());
    }
  }
}

Déploiement du modèle

Vous pouvez déployer le modèle exporté sur Vertex AI ainsi que localement. Si la clause TRANSFORM du modèle contient des fonctions de date, des fonctions de date et heure, des fonctions d'heure ou des fonctions temporelles, vous devez utiliser la bibliothèque bigquery-ml-utils dans le conteneur. La seule exception est si vous effectuez un déploiement via Model Registry, qui ne nécessite pas de modèles exportés ni de conteneurs de diffusion.

Déploiement sur Vertex AI

Déploiement local

Format de sortie de la prédiction

Cette section fournit le format de sortie de la prédiction pour les modèles exportés et pour chaque type de modèle. Tous les modèles exportés sont compatibles avec la prédiction par lot. Ils peuvent gérer plusieurs lignes d'entrée à la fois. Par exemple, chacun des exemples de formats de sortie suivants contient deux lignes d'entrée.

AUTOENCODER

+------------------------+------------------------+------------------------+
|      LATENT_COL_1      |      LATENT_COL_2      |           ...          |
+------------------------+------------------------+------------------------+
|       [FLOAT]          |         [FLOAT]        |           ...          |
+------------------------+------------------------+------------------------+
        

+------------------+------------------+------------------+------------------+
|   LATENT_COL_1   |   LATENT_COL_2   |   LATENT_COL_3   |   LATENT_COL_4   |
+------------------------+------------+------------------+------------------+
|    0.21384512    |    0.93457112    |    0.64978097    |    0.00480489    |
+------------------+------------------+------------------+------------------+
        

AUTOML_CLASSIFIER

+------------------------------------------+
| predictions                              |
+------------------------------------------+
| [{"scores":[FLOAT], "classes":[STRING]}] |
+------------------------------------------+
        

+---------------------------------------------+
| predictions                                 |
+---------------------------------------------+
| [{"scores":[1, 2], "classes":['a', 'b']},   |
|  {"scores":[3, 0.2], "classes":['a', 'b']}] |
+---------------------------------------------+
        

AUTOML_REGRESSOR

+-----------------+
| predictions     |
+-----------------+
| [FLOAT]         |
+-----------------+
        

+-----------------+
| predictions     |
+-----------------+
| [1.8, 2.46]     |
+-----------------+
        

BOOSTED_TREE_CLASSIFIER et RANDOM_FOREST_CLASSIFIER

+-------------+--------------+-----------------+
| LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL |
+-------------+--------------+-----------------+
| [FLOAT]     | [STRING]     | STRING          |
+-------------+--------------+-----------------+
        

+-------------+--------------+-----------------+
| LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL |
+-------------+--------------+-----------------+
| [0.1, 0.9]  | ['a', 'b']   | ['b']           |
+-------------+--------------+-----------------+
| [0.8, 0.2]  | ['a', 'b']   | ['a']           |
+-------------+--------------+-----------------+
        

BOOSTED_TREE_REGRESSOR et RANDOM_FOREST_REGRESSOR

+-----------------+
| predicted_label |
+-----------------+
| FLOAT           |
+-----------------+
        

+-----------------+
| predicted_label |
+-----------------+
| [1.8]           |
+-----------------+
| [2.46]          |
+-----------------+
        

DNN_CLASSIFIER

+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| ALL_CLASS_IDS | ALL_CLASSES | CLASS_IDS | CLASSES | LOGISTIC (binary only) | LOGITS | PROBABILITIES |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| [INT64]       | [STRING]    | INT64     | STRING  | FLOAT                  | [FLOAT]| [FLOAT]       |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
        

+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| ALL_CLASS_IDS | ALL_CLASSES | CLASS_IDS | CLASSES | LOGISTIC (binary only) | LOGITS | PROBABILITIES |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| [0, 1]        | ['a', 'b']  | [0]       | ['a']   | [0.36]                 | [-0.53]| [0.64, 0.36]  |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| [0, 1]        | ['a', 'b']  | [0]       | ['a']   | [0.2]                  | [-1.38]| [0.8, 0.2]    |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
        

DNN_REGRESSOR

+-----------------+
| PREDICTED_LABEL |
+-----------------+
| FLOAT           |
+-----------------+
        

+-----------------+
| PREDICTED_LABEL |
+-----------------+
| [1.8]           |
+-----------------+
| [2.46]          |
+-----------------+
        

DNN_LINEAR_COMBINED_CLASSIFIER

+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| ALL_CLASS_IDS | ALL_CLASSES | CLASS_IDS | CLASSES | LOGISTIC (binary only) | LOGITS | PROBABILITIES |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| [INT64]       | [STRING]    | INT64     | STRING  | FLOAT                  | [FLOAT]| [FLOAT]       |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
        

+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| ALL_CLASS_IDS | ALL_CLASSES | CLASS_IDS | CLASSES | LOGISTIC (binary only) | LOGITS | PROBABILITIES |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| [0, 1]        | ['a', 'b']  | [0]       | ['a']   | [0.36]                 | [-0.53]| [0.64, 0.36]  |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| [0, 1]        | ['a', 'b']  | [0]       | ['a']   | [0.2]                  | [-1.38]| [0.8, 0.2]    |
+---------------+-------------+-----------+---------+------------------------+--------+---------------+
        

DNN_LINEAR_COMBINED_REGRESSOR

+-----------------+
| PREDICTED_LABEL |
+-----------------+
| FLOAT           |
+-----------------+
        

+-----------------+
| PREDICTED_LABEL |
+-----------------+
| [1.8]           |
+-----------------+
| [2.46]          |
+-----------------+
        

KMEANS

+--------------------+--------------+---------------------+
| CENTROID_DISTANCES | CENTROID_IDS | NEAREST_CENTROID_ID |
+--------------------+--------------+---------------------+
| [FLOAT]            | [INT64]      | INT64               |
+--------------------+--------------+---------------------+
        

+--------------------+--------------+---------------------+
| CENTROID_DISTANCES | CENTROID_IDS | NEAREST_CENTROID_ID |
+--------------------+--------------+---------------------+
| [1.2, 1.3]         | [1, 2]       | [1]                 |
+--------------------+--------------+---------------------+
| [0.4, 0.1]         | [1, 2]       | [2]                 |
+--------------------+--------------+---------------------+
        

LINEAR_REG

+-----------------+
| PREDICTED_LABEL |
+-----------------+
| FLOAT           |
+-----------------+
        

+-----------------+
| PREDICTED_LABEL |
+-----------------+
| [1.8]           |
+-----------------+
| [2.46]          |
+-----------------+
       

LOGISTIC_REG

+-------------+--------------+-----------------+
| LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL |
+-------------+--------------+-----------------+
| [FLOAT]     | [STRING]     | STRING          |
+-------------+--------------+-----------------+
        

+-------------+--------------+-----------------+
| LABEL_PROBS | LABEL_VALUES | PREDICTED_LABEL |
+-------------+--------------+-----------------+
| [0.1, 0.9]  | ['a', 'b']   | ['b']           |
+-------------+--------------+-----------------+
| [0.8, 0.2]  | ['a', 'b']   | ['a']           |
+-------------+--------------+-----------------+
        

MATRIX_FACTORIZATION

Remarque : Pour le moment, nous n'acceptons que le type utilisateur en entrée et affichons les 50 meilleures paires en sortie (predicted_rating, predicted_item) triées dans l'ordre décroissant de predicted_rating.

+--------------------+--------------+
| PREDICTED_RATING | PREDICTED_ITEM |
+------------------+----------------+
| [FLOAT]          | [STRING]       |
+------------------+----------------+
        

+--------------------+--------------+
| PREDICTED_RATING | PREDICTED_ITEM |
+------------------+----------------+
| [5.5, 1.7]       | ['A', 'B']     |
+------------------+----------------+
| [7.2, 2.7]       | ['B', 'A']     |
+------------------+----------------+
        

TENSORFLOW (importé)

ACP

+-------------------------+---------------------------------+
| PRINCIPAL_COMPONENT_IDS | PRINCIPAL_COMPONENT_PROJECTIONS |
+-------------------------+---------------------------------+
|       [INT64]           |             [FLOAT]             |
+-------------------------+---------------------------------+
        

+-------------------------+---------------------------------+
| PRINCIPAL_COMPONENT_IDS | PRINCIPAL_COMPONENT_PROJECTIONS |
+-------------------------+---------------------------------+
|       [1, 2]            |             [1.2, 5.0]          |
+-------------------------+---------------------------------+
        

TRANSFORM_ONLY

Visualiser le modèle XGBoost

Vous pouvez visualiser les arbres de décision à boosting à l'aide de l'API Python plot_tree après l'exportation du modèle. Par exemple, vous pouvez exploiter Colab sans installer les dépendances :

1. Exportez le modèle d'arbre de décision à boosting vers un bucket Cloud Storage.
2. Téléchargez le fichier model.bst à partir du bucket Cloud Storage.
3. Dans un notebook Colab, importez le fichier model.bst dans Files.

4. Exécutez le code suivant dans le notebook :

   import xgboost as xgb
   import matplotlib.pyplot as plt
   
   model = xgb.Booster(model_file="model.bst")
   num_iterations = <iteration_number>
   for tree_num in range(num_iterations):
     xgb.plot_tree(model, num_trees=tree_num)
   plt.show
   

Cet exemple représente plusieurs arbres (un par itération) :

Actuellement, nous n'enregistrons pas les noms de caractéristiques dans le modèle. Vous verrez donc des noms tels que "f0", "f1", etc. Vous pouvez trouver les noms de caractéristiques correspondants dans le fichier exporté assets/model_metadata.json en utilisant ces noms (tels que "f0") comme index.

Autorisations requises

Pour exporter un modèle BigQuery ML vers Cloud Storage, vous devez disposer des autorisations d'accès au modèle BigQuery ML, des autorisations d'exécution d'une tâche d'exportation et des autorisations d'écriture des données dans le bucket Cloud Storage.

Autorisations BigQuery

• Pour exporter le modèle, vous devez au minimum disposer des autorisations bigquery.models.export. Les rôles IAM (Identity and Access Management) prédéfinis suivants disposent des autorisations bigquery.models.export :

  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

• Pour exécuter une tâche d'exportation, vous devez au moins disposer des autorisations bigquery.jobs.create. Les rôles IAM prédéfinis suivants disposent des autorisations bigquery.jobs.create :

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Autorisations Cloud Storage

• Pour écrire les données dans un bucket Cloud Storage existant, vous devez disposer des autorisations storage.objects.create. Les rôles IAM prédéfinis suivants disposent des autorisations storage.objects.create :

  • storage.objectCreator
  • storage.objectAdmin
  • storage.admin

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery ML, consultez la page Contrôle des accès.

Considérations relatives aux emplacements

Lorsque vous choisissez un emplacement pour les données, envisagez d'entreprendre les actions suivantes :

Cohébergez vos buckets Cloud Storage pour exporter des données :
• Si votre ensemble de données BigQuery se trouve dans la zone multirégionale EU, le bucket Cloud Storage contenant les données que vous exportez doit se trouver dans la même zone multirégionale ou dans un emplacement inclus dans la zone multirégionale. Par exemple, si votre ensemble de données BigQuery se trouve dans la zone multirégionale EU, le bucket Cloud Storage peut être situé dans la région de Belgique europe-west1, qui se trouve dans l'Union européenne.

  Si votre ensemble de données se trouve dans la zone multirégionale US, vous pouvez exporter des données dans un bucket Cloud Storage situé à n'importe quel emplacement.

• Si votre ensemble de données se trouve dans une région, votre bucket Cloud Storage doit se situer dans la même région. Par exemple, si votre ensemble de données se trouve dans la région de Tokyo asia-northeast1, votre bucket Cloud Storage ne peut pas se trouver dans l'emplacement multirégional ASIA.
Élaborez un plan de gestion des données :
• Si vous choisissez une ressource de stockage régionale, telle qu'un ensemble de données BigQuery ou un bucket Cloud Storage, élaborez un plan de gestion géographique des données.

Pour en savoir plus sur les emplacements Cloud Storage, consultez la page Emplacements des buckets dans la documentation de Cloud Storage.

Déplacer des données BigQuery entre des emplacements

Il n'est pas possible de modifier l'emplacement d'un ensemble de données après sa création. Toutefois, vous pouvez effectuer une copie de l'ensemble de données.

Règles de quotas

Pour en savoir plus sur les quotas appliqués aux tâches d'exportation, consultez la section Tâches d'exportation de la page "Quotas et limites".

Tarifs

L'exportation de modèles BigQuery ML est gratuite, mais les exportations sont soumises aux quotas et limites de BigQuery. Pour en savoir plus sur les tarifs de BigQuery, consultez la page Tarifs.

Une fois les données exportées, leur stockage dans Cloud Storage vous est facturé. Pour en savoir plus sur les tarifs de Cloud Storage, reportez-vous à la page Tarifs.

Étapes suivantes

• Suivez le tutoriel Exporter un modèle BigQuery ML pour la prédiction en ligne.