Atualizar os metadados do modelo

Visão geral

Nesta página, você verá como atualizar os metadados do modelo do BigQuery ML. É possível fazer isso:

Usando o Console do Google Cloud.
Use o comando bq update na ferramenta de linha de comando bq.
chamando o método da API models.patch diretamente ou usando as bibliotecas de cliente.

Os seguintes metadados do modelo podem ser atualizados:

Descrição: pode ser atualizada pelo console do Google Cloud, pela ferramenta de linha de comando bq, pela API ou pelas bibliotecas de cliente.
Rótulos: podem ser atualizados pelo console do Google Cloud, pela ferramenta de linha de comando bq, pela API ou pelas bibliotecas de cliente.
Prazo de validade: pode ser atualizado por meio da ferramenta bq, da API ou das bibliotecas de cliente.

Permissões necessárias

Para atualizar os metadados do modelo, é preciso ter o papel WRITER no conjunto de dados ou um papel do Identity and Access Management (IAM) no nível do projeto que inclui permissões bigquery.models.updateMetadata. Se você receber as permissões bigquery.models.updateMetadata no nível do projeto, poderá atualizar os metadados dos modelos em qualquer conjunto de dados no projeto. Os seguintes papéis predefinidos do IAM para envolvidos no projeto incluem permissões bigquery.models.updateMetadata:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

Para informações sobre papéis e permissões do IAM no BigQuery ML, consulte Controle de acesso.

Atualizar a descrição de um modelo

A descrição de um modelo é uma string de texto utilizada para facilitar sua identificação.

Para atualizar a descrição de um modelo:

Console

No console do Google Cloud, acesse a página do BigQuery.

Acesse a página do BigQuery
Na seção Recursos do painel de navegação, expanda os nomes do projeto e do conjunto de dados.
Clique no nome do modelo. Os modelos são indicados pelo ícone: .
Clique na guia Detalhes.
Para atualizar a descrição do modelo, clique no ícone de edição (lápis) à direita de Descrição.
Na caixa de diálogo Editar descrição, insira o texto e clique em Atualizar.

bq

Para atualizar a descrição de um modelo, emita o comando bq update com as sinalizações --model ou -m e --description.

Se você estiver atualizando um modelo em um projeto que não seja o padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

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

Em que:

[STRING] é a string de texto que descreve o modelo entre aspas;
[PROJECT_ID] é o ID do projeto;
[DATASET] é o nome do conjunto de dados.
[MODEL] é o nome do modelo.

A resposta ao comando é semelhante ao exemplo abaixo:

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

É possível confirmar suas alterações emitindo o comando bq show. Para mais informações, consulte Receber metadados do modelo.

Exemplos:

Digite o comando a seguir para atualizar a descrição de mymodel em mydataset no projeto padrão.

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

Digite o comando a seguir para atualizar a descrição de mymodel em mydataset em myotherproject.

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

API

Para atualizar a descrição de um modelo usando a API, chame o método models.patch e forneça os projectId, datasetId e modelId. Para modificar a descrição, adicione ou atualize a propriedade "description" para o recurso do modelo.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de 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 testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de 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 testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de 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 testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de 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
    )
)

Atualizar os rótulos de um modelo

Rótulos são pares de chave-valor que você anexa a um recurso. Quando você cria recursos do BigQuery ML, os rótulos são opcionais. Para mais informações, consulte Como adicionar e usar rótulos.

Para atualizar os rótulos de um modelo:

Console

No console do Google Cloud, acesse a página do BigQuery.

Acesse a página do BigQuery
Na seção Recursos do painel de navegação, expanda os nomes do projeto e do conjunto de dados.
Clique no nome do modelo. Os modelos são indicados pelo ícone: .
Clique na guia Detalhes.
Para atualizar os rótulos do modelo, clique no ícone de edição (lápis) à direita de Rótulos.
Na caixa de diálogo Editar rótulos, siga estas etapas:
- Para aplicar outros rótulos, clique em Adicionar rótulo. Cada chave pode ser usada apenas uma vez para cada conjunto de dados, mas é possível utilizar a mesma chave em conjuntos de dados diferentes dentro do mesmo projeto.
- Modifique as chaves ou valores para atualizar um rótulo.
- Clique em Update to save your changes.

bq

Para atualizar os rótulos de um modelo, emita o comando bq update com as sinalizações --model ou -m e --set_label. Repita a sinalização --set_label para adicionar ou atualizar vários rótulos.

Se você estiver atualizando um modelo em um projeto que não seja o padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

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

Em que:

[KEY:VALUE] corresponde a um par de chave-valor para um rótulo que você quer adicionar ou atualizar. Se você especificar a mesma chave que a de um rótulo atual, seu valor será atualizado. A chave precisa ser exclusiva;
[PROJECT_ID] é o ID do projeto;
[DATASET] é o nome do conjunto de dados.
[MODEL] é o nome do modelo.

A resposta ao comando é semelhante ao exemplo abaixo.

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

É possível confirmar suas alterações emitindo o comando bq show. Para mais informações, consulte Receber metadados do modelo.

Exemplos:

Para atualizar o rótulo department em mymodel, digite o comando bq update e especifique department como a chave do rótulo. Por exemplo, para atualizar o rótulo department:shipping para department:logistics, digite o comando a seguir. mydataset está em myotherproject, não no projeto padrão.

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

API

Para atualizar os rótulos de um modelo usando a API, chame o método models.patch e forneça os projectId, datasetId e modelId. Para modificar os rótulos, adicione ou atualize a propriedade "labels" para o recurso do modelo.

Como atualizar o prazo de validade de um modelo

O prazo de validade é um valor de carimbo de data/hora que determina quando o modelo será excluído. É possível definir esse prazo durante a criação do modelo por meio da CLI, da API ou das bibliotecas de cliente. É possível, ainda, estabelecer ou atualizar o prazo de validade depois que o modelo for criado. Ele também é chamado de "tempo de vida" ou TTL, na sigla em inglês.

Caso você não estipule um prazo de validade, o modelo nunca expirará e será preciso fazer sua exclusão manualmente.

O valor do prazo de validade é expresso de forma diferente dependendo de onde ele for definido. Use um método que garanta o nível apropriado de granularidade:

Na ferramenta de linha de comando, o prazo de validade é expresso em segundos a partir do horário UTC atual. Quando ele é especificado, o valor inteiro em segundos é adicionado ao carimbo de data/hora UTC atual.
Na API, o prazo é expresso em milissegundos desde o período. Se um valor menor do que o carimbo de data/hora atual for estabelecido, o modelo vai expirar imediatamente.

Para atualizar o prazo de validade de um modelo, siga estas etapas:

Console

No momento, não é possível definir ou atualizar o prazo de validade de um modelo no console do Google Cloud.

bq

Para atualizar o prazo de validade de um modelo, emita o comando bq update com as sinalizações --model ou -m e --expiration.

Se você estiver atualizando um modelo em um projeto que não seja o padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

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

Em que:

[INTEGER] é o ciclo de vida (em segundos) para o modelo. O valor mínimo é de 3.600 segundos (uma hora). O prazo de validade é a soma do horário UTC atual com o valor inteiro.
[PROJECT_ID] é o ID do projeto;
[DATASET] é o nome do conjunto de dados.
[MODEL] é o nome do modelo.

A resposta ao comando é semelhante ao exemplo abaixo.

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

É possível confirmar suas alterações emitindo o comando bq show. Para mais informações, consulte Receber metadados do modelo.

Exemplos:

Insira o seguinte comando para atualizar o prazo de validade de mymodel em mydataset para 5 dias (432.000 segundos). mydataset está em seu projeto padrão.

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

Insira o seguinte comando para atualizar o prazo de validade de mymodel em mydataset para 5 dias (432.000 segundos). mydataset está em myotherproject, e não no projeto padrão.

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

API

Para atualizar a validade de um modelo usando a API, chame o método models.patch e forneça os projectId, datasetId e modelId. Já para atualizar a validade, adicione ou atualize a propriedade "expirationTime" para o recurso do modelo. A propriedade "expirationTime" é expressa em milissegundos desde o período.

A seguir

Para uma visão geral sobre ML do BigQuery, consulte Introdução ao ML do BigQuery.
Para começar a usar o BigQuery ML, consulte Criar modelos de machine learning no BigQuery ML.
Para mais informações sobre como utilizar os modelos, consulte: