Mettre à jour les métadonnées de modèle

Cette page explique comment mettre à jour les métadonnées de modèle BigQuery ML à l'aide des méthodes suivantes :

  • Utiliser la console Google Cloud
  • Exécuter la commande bq update dans l'outil de ligne de commande bq
  • Appeler directement la méthode d'API models.patch ou utiliser les bibliothèques clientes

Vous pouvez mettre à jour les métadonnées de modèle suivantes :

  • Description : peut être mise à jour à l'aide de la console Google Cloud, de l'outil de ligne de commande bq, de l'API ou des bibliothèques clientes.
  • Étiquettes : peuvent être mises à jour à l'aide de la console Google Cloud, de l'outil de ligne de commande bq, de l'API ou des bibliothèques clientes.
  • Heure d'expiration : peut être mise à jour à l'aide de l'outil bq, de l'API ou des bibliothèques clientes.

Autorisations requises

Pour mettre à jour des métadonnées de modèle, vous devez disposer du rôle WRITER au niveau de l'ensemble de données, ou d'un rôle Identity and Access Management (IAM) au niveau du projet incluant les autorisations bigquery.models.updateMetadata. Si vous disposez des autorisations bigquery.models.updateMetadata au niveau du projet, vous pouvez mettre à jour les métadonnées de modèle dans n'importe quel ensemble de données du projet. Les rôles IAM prédéfinis suivants au niveau du projet incluent des autorisations bigquery.models.updateMetadata :

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

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

Mettre à jour la description d'un modèle

La description d'un modèle est une chaîne de texte permettant d'identifier le modèle.

Pour mettre à jour la description d'un modèle, procédez comme suit :

Console

  1. Dans Google Cloud Console, accédez à la page "BigQuery".

    Accéder à la page "BigQuery"

  2. Dans le volet Explorateur, développez votre projet, puis un ensemble de données.

  3. Développez le dossier Modèles dans l'ensemble de données, puis cliquez sur un nom de modèle pour le sélectionner.

  4. Cliquez sur l'onglet Détails.

  5. Pour mettre à jour la description du modèle, cliquez sur Modifier .

  6. Dans la boîte de dialogue Modifier les détails, mettez à jour la description, puis cliquez sur Enregistrer.

bq

Pour mettre à jour la description d'un modèle, exécutez la commande bq update avec les options --model ou -m et l'option --description.

Si vous mettez à jour un modèle dans un projet autre que votre projet par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : [PROJECT_ID]:[DATASET].

bq update --model --description "[STRING]" PROJECT_ID:DATASET.MODEL

Remplacez les éléments suivants :

  • STRING est la chaîne de texte décrivant votre modèle entre guillemets.
  • PROJECT_ID est l'ID de votre projet.
  • DATASET est le nom de l'ensemble de données.
  • MODEL est le nom du modèle.

Le résultat de la commande correspond à ceci :

Model 'myproject.mydataset.mymodel' successfully updated.

Vous pouvez confirmer vos modifications en exécutant la commande bq show. Pour en savoir plus, consultez la section Obtenir les métadonnées du modèle.

Exemples :

Saisissez la commande suivante pour mettre à jour la description de mymodel dans mydataset dans votre projet par défaut.

bq update --model --description "My updated description" \
mydataset.mymodel

Saisissez la commande suivante pour mettre à jour la description de mymodel dans mydataset dans myotherproject.

bq update --model --description "My updated description" \
myotherproject:mydataset.mymodel

API

Pour mettre à jour la description d'un modèle à l'aide de l'API, appelez la méthode models.patch et spécifiez les paramètres projectId, datasetId et modelId. Pour modifier la description, ajoutez ou mettez à jour la propriété "description" de la ressource de modèle.

Go

Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Go.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateModelDescription demonstrates fetching BigQuery ML model metadata and updating the
// Description metadata.
func updateModelDescription(projectID, datasetID, modelID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// modelID := "mymodel"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	model := client.Dataset(datasetID).Model(modelID)
	oldMeta, err := model.Metadata(ctx)
	if err != nil {
		return fmt.Errorf("couldn't retrieve model metadata: %w", err)
	}
	update := bigquery.ModelMetadataToUpdate{
		Description: "This model was modified from a Go program",
	}
	if _, err = model.Update(ctx, update, oldMeta.ETag); err != nil {
		return fmt.Errorf("couldn't update model: %w", err)
	}
	return nil
}

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Model;
import com.google.cloud.bigquery.ModelId;

// Sample to update description on a model
public class UpdateModelDescription {

  public static void runUpdateModelDescription() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String modelName = "MY_MODEL_NAME";
    String newDescription = "A really great model.";
    updateModelDescription(datasetName, modelName, newDescription);
  }

  public static void updateModelDescription(
      String datasetName, String modelName, String newDescription) {
    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();

      Model model = bigquery.getModel(ModelId.of(datasetName, modelName));
      bigquery.update(model.toBuilder().setDescription(newDescription).build());
      System.out.println("Model description updated successfully to " + newDescription);
    } catch (BigQueryException e) {
      System.out.println("Model description was not updated \n" + e.toString());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration pour Node.js du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Node.js.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function updateModel() {
  // Updates a model's metadata.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";
  // const modelId = "my__model";

  const metadata = {
    description: 'A really great model.',
  };

  const dataset = bigquery.dataset(datasetId);
  const [apiResponse] = await dataset.model(modelId).setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${modelId} description: ${newDescription}`);
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set model_id to the ID of the model to fetch.
# model_id = 'your-project.your_dataset.your_model'

model = client.get_model(model_id)  # Make an API request.
model.description = "This model was modified from a Python program."
model = client.update_model(model, ["description"])  # Make an API request.

full_model_id = "{}.{}.{}".format(model.project, model.dataset_id, model.model_id)
print(
    "Updated model '{}' with description '{}'.".format(
        full_model_id, model.description
    )
)

Mettre à jour les étiquettes d'un modèle

Les étiquettes sont des paires clé/valeur que vous pouvez associer à une ressource. Lorsque vous créez des ressources BigQuery ML, l'attribution des étiquettes est facultative. Pour en savoir plus, consultez la section Ajouter et utiliser des étiquettes.

Pour mettre à jour les étiquettes d'un modèle, procédez comme suit :

Console

  1. Dans le volet Explorateur, développez votre projet, puis un ensemble de données.

  2. Développez le dossier Modèles dans l'ensemble de données, puis cliquez sur un nom de modèle pour le sélectionner.

  3. Cliquez sur l'onglet Détails.

  4. Pour mettre à jour les étiquettes du modèle, cliquez sur Modifier .

  5. Dans la boîte de dialogue Modifier les détails, ajoutez, supprimez ou modifiez des libellés, puis cliquez sur Enregistrer.

bq

Pour mettre à jour les étiquettes d'un modèle, exécutez la commande bq update avec l'option --model ou -m et l'option --set_label. Répétez l'option --set_label pour ajouter ou mettre à jour plusieurs étiquettes.

Si vous mettez à jour un modèle dans un projet autre que votre projet par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : [PROJECT_ID]:[DATASET].

bq update --model --set_label KEY:VALUE \
PROJECT_ID:DATASET.MODEL

Remplacez les éléments suivants :

  • KEY:VALUE est une paire clé/valeur pour une étiquette que vous souhaitez ajouter ou mettre à jour. Si vous spécifiez une clé associée à un libellé existant, la valeur de celui-ci est mise à jour. La clé doit être unique.
  • PROJECT_ID est l'ID de votre projet.
  • DATASET est le nom de l'ensemble de données.
  • MODEL est le nom du modèle.

Le résultat de la commande correspond à ceci :

Model 'myproject.mydataset.mymodel' successfully updated.

Vous pouvez confirmer vos modifications en exécutant la commande bq show. Pour en savoir plus, consultez la section Obtenir les métadonnées du modèle.

Exemples :

Pour mettre à jour l'étiquette department sur mymodel, saisissez la commande bq update et spécifiez department comme clé d'étiquette. Par exemple, si vous souhaitez remplacer l'étiquette department:shipping par department:logistics, saisissez la commande ci-dessous. mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

bq update --model --set_label department:logistics \
myotherproject:mydataset.mymodel

API

Pour mettre à jour les étiquettes d'un modèle à l'aide de l'API, appelez la méthode models.patch et spécifiez les paramètres projectId, datasetId et modelId. Pour modifier les étiquettes, ajoutez ou mettez à jour la propriété "labels" de la ressource de modèle.

Mettre à jour le délai d'expiration d'un modèle

L'heure d'expiration d'un modèle est une valeur d'horodatage qui détermine le moment où un modèle est supprimé. Vous pouvez définir l'heure d'expiration d'un modèle lors de sa création à l'aide de la CLI, de l'API ou des bibliothèques clientes. Vous pouvez également définir ou mettre à jour l'heure d'expiration d'un modèle après sa création. L'heure d'expiration d'un modèle est souvent appelée "Durée de vie" ou valeur TTL.

Si vous ne définissez pas d'heure d'expiration d'un modèle, celui-ci n'expire jamais, et vous devez le supprimer manuellement.

La valeur de l'heure d'expiration est exprimée différemment selon l'endroit où elle est définie. Parmi les méthodes ci-dessous, utilisez celle qui vous donne le niveau de précision adéquat.

  • Dans l'outil de ligne de commande, l'expiration est exprimée en secondes à partir de l'heure UTC actuelle. Lorsque vous spécifiez l'expiration sur la ligne de commande, la valeur entière en secondes est ajoutée à l'horodatage UTC actuel.
  • Dans l'API, l'expiration est exprimée en millisecondes depuis l'époque. Si vous spécifiez une valeur d'expiration inférieure à l'horodatage actuel, le modèle expire immédiatement.

Pour mettre à jour l'heure d'expiration d'un modèle, procédez comme suit :

Console

La définition ou la mise à jour de l'heure d'expiration d'un modèle n'est pas possible avec la console Google Cloud.

bq

Pour mettre à jour l'heure d'expiration d'un modèle, exécutez la commande bq update avec l'option --model ou -m et l'option --expiration.

Si vous mettez à jour un modèle dans un projet autre que votre projet par défaut, ajoutez l'ID du projet à l'ensemble de données, en respectant le format suivant : [PROJECT_ID]:[DATASET].

bq update --model --expiration INTEGER \
PROJECT_ID:DATASET.MODEL

Remplacez les éléments suivants :

  • INTEGER est la durée de vie (en secondes) du modèle. La valeur minimale est de 3 600 secondes (une heure). L'heure d'expiration correspond à l'heure actuelle plus la valeur entière.
  • PROJECT_ID est l'ID de votre projet.
  • DATASET est le nom de l'ensemble de données.
  • MODEL est le nom du modèle.

Le résultat de la commande correspond à ceci :

Model 'myproject.mydataset.mymodel' successfully updated.

Vous pouvez confirmer vos modifications en exécutant la commande bq show. Pour en savoir plus, consultez la section Obtenir les métadonnées du modèle.

Exemples :

Saisissez la commande suivante pour faire passer le délai d'expiration de mymodel dans mydataset à cinq jours (432 000 secondes). mydataset se trouve dans votre projet par défaut.

bq update --model --expiration 432000 mydataset.mymodel

Saisissez la commande suivante pour faire passer le délai d'expiration de mymodel dans mydataset à cinq jours (432 000 secondes). mydataset se trouve dans myotherproject, et non dans votre projet par défaut.

bq update --model --expiration 432000 myotherproject:mydataset.mymodel

API

Pour mettre à jour l'expiration d'un modèle à l'aide de l'API, appelez la méthode models.patch et spécifiez les paramètres projectId, datasetId et modelId. Pour modifier l'heure d'expiration, ajoutez ou mettez à jour la propriété "expirationTime" de la ressource de modèle. "expirationTime" est exprimé en millisecondes depuis l'époque.

Étapes suivantes