Actualizar metadatos de modelos

Descripción general

En esta página, se muestra cómo actualizar los metadatos del modelo de BigQuery ML. Para actualizar los metadatos del modelo, haz lo siguiente:

Usa la consola de Google Cloud
Usa el comando bq update en la herramienta de línea de comandos de bq.
Llama directamente al método models.patch de la API o usa las bibliotecas cliente.

Se pueden actualizar los siguientes metadatos del modelo:

Descripción: Se puede actualizar mediante la consola de Google Cloud, la herramienta de línea de comandos de bq, la API o las bibliotecas cliente.
Etiquetas: se pueden actualizar mediante la consola de Google Cloud, la herramienta de línea de comandos de bq, la API o las bibliotecas cliente.
Hora de vencimiento: se puede actualizar mediante la herramienta de bq, la API o las bibliotecas cliente.

Permisos necesarios

Para actualizar los metadatos del modelo, debes tener asignado el rol WRITER en el conjunto de datos o un rol de administración de identidades y accesos (IAM) a nivel de proyecto que incluye permisos bigquery.models.updateMetadata. Si se te otorgan permisos bigquery.models.updateMetadata a nivel de proyecto, puedes actualizar los metadatos de los modelos en cualquier conjunto de datos del proyecto. Las siguientes funciones predefinidas de IAM a nivel de proyecto incluyen los permisos bigquery.models.updateMetadata:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

Para obtener más información sobre los roles de IAM y los permisos en BigQuery ML, consulta Control de acceso.

Actualiza la descripción de un modelo

La descripción de un modelo es una string de texto que se usa para identificar fácilmente el modelo.

Para actualizar la descripción de un modelo, haz lo siguiente:

Console

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a la página de BigQuery
En el panel de navegación, en la sección Recursos, expande el nombre de tu proyecto y del conjunto de datos.
Haz clic en el nombre de tu modelo. Los modelos se indican con el ícono del modelo: .
Haz clic en la pestaña Detalles.
Para actualizar la descripción del modelo, haz clic en el ícono de edición (lápiz) a la derecha de la Descripción.
En el diálogo Editar descripción, ingresa tu texto y, luego, haz clic en Actualizar.

bq

Para actualizar la descripción de un modelo, ejecuta el comando bq update con la marca --model o -m y la marca --description.

Si estás actualizando un modelo de un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: [PROJECT_ID]:[DATASET].

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

Donde:

[STRING] es la string de texto que describe tu modelo entre comillas.
[PROJECT_ID] es el ID del proyecto.
[DATASET] es el nombre del conjunto de datos.
[MODEL] es el nombre del modelo.

El resultado del comando se ve de la siguiente manera:

Model '[PROJECT_ID]:[DATASET].[MODEL]' successfully updated.

Puedes confirmar los cambios ejecutando el comando bq show. Para obtener más información, consulta Obtén metadatos del modelo.

Ejemplos:

Ingresa el siguiente comando para actualizar la descripción de mymodel en mydataset en tu proyecto predeterminado.

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

Ingresa el siguiente comando para actualizar la descripción de mymodel en mydataset en myotherproject.

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

API

Para actualizar la descripción de un modelo mediante la API, llama al método models.patch y especifica projectId, datasetId y modelId. Si deseas modificar la descripción, agrega o actualiza la propiedad “description” del recurso del modelo.

Comienza a usarlo

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.


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

Actualiza las etiquetas de un modelo

Las etiquetas son pares clave-valor que puedes adjuntar a un recurso. Cuando creas recursos de BigQuery ML, las etiquetas son opcionales. Para obtener más información, consulta Agrega y usa etiquetas.

Para actualizar las etiquetas de un modelo, haz lo siguiente:

Console

En la consola de Google Cloud, ve a la página de BigQuery.

Ir a la página de BigQuery
En el panel de navegación, en la sección Recursos, expande el nombre de tu proyecto y del conjunto de datos.
Haz clic en el nombre de tu modelo. Los modelos se indican con el ícono del modelo: .
Haz clic en la pestaña Detalles.
Para actualizar las etiquetas del modelo, haz clic en el ícono de edición (lápiz) a la derecha de Etiquetas.
En el diálogo Editar etiquetas, haz lo siguiente:
- Para aplicar etiquetas adicionales, haz clic en Agregar etiqueta (Add Label). Se puede usar cada clave solo una vez por conjunto de datos, pero puedes usar la misma clave en otros conjuntos de datos del mismo proyecto.
- Modifica las claves o valores existentes para actualizar una etiqueta.
- Haz clic en Actualizar para guardar los cambios.

bq

Para actualizar las etiquetas de un modelo, ejecuta el comando bq update con la marca --model o -m y la marca --set_label. Repite la marca --set_label para agregar o actualizar varias etiquetas.

Si estás actualizando un modelo de un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: [PROJECT_ID]:[DATASET].

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

Donde:

[KEY:VALUE] corresponde a un par clave-valor de una etiqueta que deseas agregar o actualizar. Si especificas la misma clave que una etiqueta existente, se actualiza el valor de la etiqueta existente. La clave debe ser exclusiva.
[PROJECT_ID] es el ID del proyecto.
[DATASET] es el nombre del conjunto de datos.
[MODEL] es el nombre del modelo.

El resultado del comando se ve de la siguiente manera.

Model '[PROJECT_ID]:[DATASET].[MODEL]' successfully updated.

Puedes confirmar los cambios ejecutando el comando bq show. Para obtener más información, consulta Obtén metadatos del modelo.

Ejemplos:

Para actualizar la etiqueta department en mymodel, ingresa el comando bq update y especifica department como clave de etiqueta. Por ejemplo, para actualizar la etiqueta department:shipping a department:logistics, ingresa el siguiente comando. mydataset está en myotherproject, no en tu proyecto predeterminado.

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

API

Para actualizar las etiquetas de un modelo con la API, llama al método models.patch y proporciona projectId, datasetId y modelId. A fin de modificar las etiquetas, agrega o actualiza la propiedad “labels” del recurso del modelo.

Actualiza la hora de vencimiento de un modelo

La hora de vencimiento de un modelo es un valor de marca de tiempo que determina cuándo se borra el modelo. Puedes configurar la hora de vencimiento de un modelo cuando lo creas mediante el uso de la CLI, la API o de las bibliotecas cliente. También puedes configurar o actualizar la hora de vencimiento en un modelo después de su creación. Se suele hablar de "tiempo de vida" o TTL para referirse a la hora de vencimiento de un modelo.

Si no configuras una hora de vencimiento en un modelo, este nunca vence y debes borrarlo manualmente.

El valor para la hora de vencimiento se expresa de manera diferente según dónde se configure el valor. Usa el método que te dé el nivel apropiado de detalle:

En la herramienta de línea de comandos, el vencimiento se expresa en segundos a partir la hora UTC actual. Cuando especificas el vencimiento en la línea de comandos, se suma el número entero en segundos a la marca de tiempo UTC actual.
En la API, el vencimiento se expresa en milisegundos desde el ciclo de entrenamiento. Si especificas un valor de vencimiento menor que la marca de tiempo actual, el modelo vence inmediatamente.

Para actualizar la hora de vencimiento de un modelo, haz lo siguiente:

Console

En este momento, la consola de Google Cloud no admite la configuración o actualización de la hora de vencimiento de un modelo.

bq

Para actualizar la hora de vencimiento de un modelo, ejecuta el comando bq update con la marca --model o -m y la marca --expiration.

Si estás actualizando un modelo de un proyecto que no es tu proyecto predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: [PROJECT_ID]:[DATASET].

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

Donde:

[INTEGER] es la vida útil (en segundos) del modelo. El valor mínimo es 3,600 segundos (una hora). La hora de vencimiento se evalúa según la hora UTC actual más el número entero.
[PROJECT_ID] es el ID del proyecto.
[DATASET] es el nombre del conjunto de datos.
[MODEL] es el nombre del modelo.

El resultado del comando se ve de la siguiente manera.

Model '[PROJECT_ID]:[DATASET].[MODEL]' successfully updated.

Puedes confirmar los cambios ejecutando el comando bq show. Para obtener más información, consulta Obtén metadatos del modelo.

Ejemplos:

Ingresa el comando siguiente a fin de actualizar la fecha de vencimiento de mymodel en mydataset a 5 días (432,000 segundos). mydataset está en tu proyecto predeterminado.

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

Ingresa el comando siguiente a fin de actualizar la fecha de vencimiento de mymodel en mydataset a 5 días (432,000 segundos). mydataset está en myotherproject, no en el proyecto predeterminado.

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

API

Para actualizar el vencimiento de un modelo con la API, llama al método models.patch y proporciona projectId, datasetId y modelId. A fin de modificar el vencimiento, agrega o actualiza la propiedad “expirationTime” del recurso del modelo. "expirationTime" se expresa en milisegundos desde el ciclo de entrenamiento.

Qué sigue

Para obtener una descripción general de BigQuery ML, consulta Introducción a BigQuery ML.
Para comenzar a usar BigQuery ML, consulta Crea modelos de aprendizaje automático en BigQuery ML.
Para obtener más información sobre cómo trabajar con modelos, consulta: