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 facilement le modèle.

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

Console

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

Accéder à BigQuery
Dans le panneau de navigation, dans la section Ressources, développez le nom de votre projet et celui de l'ensemble de données.
Cliquez sur le nom de votre modèle. Les modèles sont indiqués par l'icône .
Cliquez sur l'onglet Détails.
Pour mettre à jour la description du modèle, cliquez sur l'icône d'édition (le crayon) à droite de Description.
Dans la boîte de dialogue Modifier la description, saisissez votre texte, puis cliquez sur Mettre à jour.

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]

Où :

[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 '[PROJECT_ID]:[DATASET].[MODEL]' 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.

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.

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


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

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

Accéder à BigQuery
Dans le panneau de navigation, dans la section Ressources, développez le nom de votre projet et celui de l'ensemble de données.
Cliquez sur le nom de votre modèle. Les modèles sont indiqués par l'icône .
Cliquez sur l'onglet Détails.
Pour mettre à jour les étiquettes du modèle, cliquez sur l'icône d'édition (le crayon) à droite de Étiquettes.
Dans la boîte de dialogue Modifier les étiquettes, effectuez les opérations suivantes :
- Pour attribuer des libellés supplémentaires, cliquez sur Ajouter un libellé. Chaque clé ne peut être utilisée qu'une seule fois par ensemble de données, mais vous pouvez exploiter la même clé pour plusieurs ensembles de données au sein d'un même projet.
- Modifiez les clés ou valeurs existantes pour mettre à jour un libellé.
- Cliquez sur Mettre à jour pour enregistrer vos modifications.

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]

Où :

[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 '[PROJECT_ID]:[DATASET].[MODEL]' 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 actuellement 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]

Où :

[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 '[PROJECT_ID]:[DATASET].[MODEL]' 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

Pour obtenir plus d'informations sur BigQuery ML, consultez la page Présentation de BigQuery ML.
Consultez la page Créer des modèles de machine learning dans BigQuery ML pour faire vos premiers pas avec BigQuery ML.
Pour en savoir plus sur l'utilisation des modèles, consultez les pages suivantes :