Exporter des modèles

Aperçu

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 :

  • À l'aide de Cloud Console
  • Utilisez l'instruction EXPORT MODEL.
  • Utiliser 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 :

  • AUTOML_CLASSIFIER
  • AUTOML_REGRESSOR
  • BOOSTED_TREE_CLASSIFIER
  • BOOSTED_TREE_REGRESSOR
  • DNN_CLASSIFIER
  • DNN_REGRESSOR
  • KMEANS
  • LINEAR_REG
  • LOGISTIC_REG
  • MATRIX_FACTORIZATION
  • TENSORFLOW (modèles TensorFlow importés)

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.

Type de modèle Format du modèle d'exportation Exemple de fichiers exportés
AUTOML_CLASSIFIER TensorFlow SavedModel (version 2.1.0) gcs_bucket/
  assets/
    f1.txt
    f2.txt
  saved_model.pb
  variables/
    variables.data-00-of-01
    variables.index
AUTOML_REGRESSOR
DNN_CLASSIFIER TensorFlow SavedModel (version TF 1.15 ou ultérieure)
DNN_REGRESSOR
KMEANS
LINEAR_REGRESSOR
LOGISTIC_REG
MATRIX_FACTORIZATION
BOOSTED_TREE_CLASSIFIER Booster (XGBoost 0,82) gcs_bucket/
  assets/
    0.txt
    1.txt
    model_metadata.json
  main.py
  model.bst
  xgboost_predictor-0.1.tar.gz
    ....
     predictor.py
    ....


main.py est destiné à une exécution locale. Pour en savoir plus, consultez la section Déploiement du modèle.
BOOSTED_TREE_REGRESSOR
TENSORFLOW (importé) Modèle SavedModel TensorFlow Exactement les mêmes fichiers que lors de l'importation du modèle

Le modèle ne contient pas d'informations sur le développement fonctionnel mis en œuvre dans l'instruction SELECT pendant l'entraînement. Vous devez donc convertir manuellement les données d'entrée avant de les utiliser dans le modèle exporté.

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.
    • La clause BigQuery ML Transform a été utilisée pour l'extraction de caractéristiques.
  • Les modèles exportés pour les types de modèle AUTOML_REGRESSOR et AUTOML_CLASSIFIER ne sont pas compatibles avec le déploiement AI Platform 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.

  • Les fonctionnalités liées aux clés de chiffrement gérées par le client ne sont pas compatibles avec l'exportation de modèles.

Exporter des modèles BigQuery ML

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

Console

  1. Ouvrez la page "BigQuery" dans Cloud Console.

    Accéder à BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet et cliquez sur un ensemble de données pour le développer. Recherchez et cliquez sur le modèle que vous exportez.

  3. Dans la fenêtre, à droite, cliquez sur Export Model (Exporter le modèle).

    Exporter le modèle

  4. Dans la boîte de dialogue Exporter le modèle vers Cloud Storage, procédez comme suit :

    • Dans le champ Sélectionner l'emplacement Cloud Storage, recherchez l'emplacement du bucket ou du dossier dans lequel vous souhaitez exporter le modèle.
    • Cliquez sur Exporter pour exporter le modèle.

Pour vérifier la progression de la tâche, consultez en haut de la fenêtre de navigation l'historique de la tâche pour une tâche d'exportation.

SQL

L'instruction EXPORT MODEL vous permet d'exporter des modèles BigQuery ML vers Cloud Storage à l'aide de la syntaxe de requête SQL standard.

Pour exporter un modèle BigQuery ML dans Cloud Console à l'aide de l'instruction EXPORT MODEL, procédez comme suit :

  1. Dans Cloud Console, ouvrez la page "BigQuery".

    Accéder à BigQuery

  2. Cliquez sur Saisir une nouvelle requête.

  3. Dans le champ Éditeur de requête, saisissez votre instruction EXPORT MODEL.

    La requête suivante permet d'exporter un modèle nommé myproject.mydataset.mymodel vers un bucket Cloud Storage avec l'URI URI gs://bucket/path/to/saved_model/.

     EXPORT MODEL `myproject.mydataset.mymodel`
     OPTIONS(URI = 'gs://bucket/path/to/saved_model/')
     

  4. Cliquez sur Run (Exécuter). Lorsque la requête est terminée, la ligne suivante apparaît dans le volet Résultats de la requête : Successfully exported model.

bq

Exécutez la commande bq extract avec l'option --model.

(Facultatif) Spécifiez l'option --destination_format et choisissez le format du modèle exporté. (Facultatif) Spécifiez l'option --location et définissez la valeur correspondant à votre emplacement.

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

Où :

  • location est le nom du site. L'option --location est facultative. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de l'option sur asia-northeast1. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc.
  • destination_format est le format du modèle exporté : ML_TF_SAVED_MODEL (par défaut) ou ML_XGBOOST_BOOSTER.
  • project_id est l'ID de votre projet.
  • dataset est le nom de l'ensemble de données source.
  • model est le modèle que vous exportez.
  • bucket est le nom du bucket Cloud Storage vers lequel vous exportez les données. L'ensemble de données BigQuery et le bucket Cloud Storage doivent se trouver dans le même emplacement.
  • model_folder est le nom du dossier dans lequel les fichiers de modèle exportés seront écrits.

Exemples :

Par exemple, la commande suivante exporte mydataset.mymodel au format TensorFlow SavedModel vers un bucket Cloud Storage nommé mymodel_folder.

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

La valeur par défaut de destination_format est ML_TF_SAVED_MODEL.

La commande suivante exporte mydataset.mymodel au format Booster XGBoost vers un bucket Cloud Storage nommé mymodel_folder.

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

API

Pour exporter le modèle, créez une tâche extract et renseignez la configuration de la tâche.

(Facultatif) Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.

  1. Créez une tâche d'extraction qui pointe vers le modèle BigQuery ML et la destination Cloud Storage.

  2. Spécifiez le modèle source à l'aide de l'objet de configuration sourceModel qui contient l'ID du projet, l'ID de l'ensemble de données et l'ID du modèle.

  3. La propriété destination URI(s) doit être complète, au format gs://bucket/model_folder.

  4. Spécifiez le format de destination en définissant la propriété configuration.extract.destinationFormat. Par exemple, pour exporter un modèle en arbre de décision à boosting, définissez cette propriété sur la valeur ML_XGBOOST_BOOSTER.

  5. Pour vérifier l'état de la tâche, appelez jobs.get(job_id) avec l'ID de la tâche renvoyée par la requête initiale.

    • Si la réponse est status.state = DONE, la tâche a bien été exécutée.
    • Si la propriété status.errorResult est présente, la requête a échoué. Cet objet inclura des informations décrivant le problème rencontré.
    • Si la propriété status.errorResult est absente, la tâche a bien été exécutée. Toutefois, des erreurs non fatales ont pu se produire. La propriété status.errors de l'objet de la tâche répertorie ces erreurs.

Remarques concernant l'API :

  • Nous vous recommandons de générer un ID unique et de le transmettre en tant que jobReference.jobId lorsque vous appelez jobs.insert pour créer une tâche. Cette approche offre une protection plus robuste contre les pannes réseau, car le client peut lancer une requête ou effectuer de nouvelles tentatives en utilisant l'ID de tâche connu.

  • L'appel de jobs.insert avec un ID de tâche donné est idempotent. En d'autres termes, vous pouvez effectuer autant de tentatives que vous le souhaitez avec le même ID de tâche. L'une de ces opérations tout au plus aboutira.

Java

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 Google Cloud AI Platform ainsi que localement.

Déploiement sur AI Platform

Format du modèle d'exportation Déploiement
SavedModel Tensorflow (modèles autres qu'AutoML) Déployer un modèle SavedModel TensorFlow (version d'exécution 1.15 ou ultérieure)
SavedModel Tensorflow (modèles AutoML) Incompatible
Booster XGBoost Routine de prédiction personnalisée (version d'exécution 1.15)

Remarque : Comme les informations sur le prétraitement et le post-traitement sont enregistrées dans les fichiers exportés, vous devez utiliser une routine de prédiction personnalisée pour déployer le modèle avec les fichiers exportés supplémentaires.

Déploiement local

Format du modèle d'exportation Déploiement
SavedModel Tensorflow (modèles autres qu'AutoML) Le modèle SavedModel est un format standard que vous pouvez déployer dans le conteneur Docker de Tensorflow Serving.

Vous pouvez également exploiter l'exécution locale de la prédiction en ligne AI Platform.
SavedModel Tensorflow (modèles AutoML) Exécutez le conteneur AutoML.
Booster XGBoost Pour exécuter des modèles Booster XGBoost localement, vous pouvez utiliser le fichier main.py exporté :
  1. Téléchargez tous les fichiers de Cloud Storage dans le répertoire local.
  2. Décompressez le fichier predictor.py de xgboost_predictor-0.1.tar.gz dans le répertoire local.
  3. Exécutez main.py (consultez les instructions dans main.py).

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.

AUTOML_CLASSIFIER

Format de sortie de la prédiction Exemple de sortie

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

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

AUTOML_REGRESSOR

Format de sortie de la prédiction Exemple de sortie

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

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

BOOSTED_TREE_CLASSIFIER

Format de sortie de la prédiction Exemple de sortie

+-------------+--------------+-----------------+
| 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

Format de sortie de la prédiction Exemple de sortie

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

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

DNN_CLASSIFIER

Format de sortie de la prédiction Exemple de sortie

+---------------+-------------+-----------+---------+------------------------+--------+---------------+
| 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

Format de sortie de la prédiction Exemple de sortie

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

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

KMEANS

Format de sortie de la prédiction Exemple de sortie

+--------------------+--------------+---------------------+
| 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

Format de sortie de la prédiction Exemple de sortie

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

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

LOGISTIC_REG

Format de sortie de la prédiction Exemple de sortie

+-------------+--------------+-----------------+
| 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.

Format de sortie de la prédiction Exemple de sortie

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

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

TENSORFLOW (importé)

Format de sortie de la prédiction
Identique au modèle importé

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

Exporter le modèle

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 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. Pour en savoir plus sur les rôles au niveau de l'ensemble de données, consultez la section Rôles de base pour les ensembles de données de la documentation BigQuery.

Considérations relatives aux zones

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

  • Cohéberger vos buckets Cloud Storage pour exporter des données
    • Lorsque vous exportez des données, le bucket Cloud Storage régional ou multirégional doit se trouver dans le même emplacement que l'ensemble de données BigQuery ML. Par exemple, si votre ensemble de données BigQuery ML se trouve dans l'emplacement multirégional UE (Union européenne), le bucket Cloud Storage contenant les données que vous exportez doit se trouver dans un emplacement régional ou multirégional situé dans l'UE.
    • Si votre ensemble de données se trouve dans un emplacement régional, le bucket Cloud Storage doit être un bucket régional du même emplacement. Par exemple, si votre ensemble de données se trouve dans la région Tokyo, le bucket Cloud Storage doit être un bucket régional situé à Tokyo.
    • Exception : Si votre ensemble de données se trouve dans la zone multirégionale États-Unis, vous pouvez exporter des données dans un bucket Cloud Storage situé dans n'importe quelle zone régionale ou multirégionale.
  • Élaborer un plan de gestion des données
    • Si vous choisissez une ressource de stockage régionale, telle qu'un ensemble de données BigQuery ML 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.

Étape suivante