Como exportar modelos

Visão geral

Nesta página, você aprenderá como exportar modelos do BigQuery ML. É possível exportar modelos do BigQuery ML para o Cloud Storage e usá-los para realizar previsões on-line ou editá-los no Python. Há três maneiras de exportar modelos:

  • usando o Console do Cloud;
  • usando a instrução EXPORT MODEL.
  • use o comando bq extract na ferramenta de linha de comando bq.
  • enviando um job extract por meio da API ou das bibliotecas de cliente.

Os seguintes tipos de modelo podem ser exportados:

  • AUTOML_CLASSIFIER
  • AUTOML_REGRESSOR
  • BOOSTED_TREE_CLASSIFIER
  • BOOSTED_TREE_REGRESSOR
  • DNN_CLASSIFIER
  • DNN_REGRESSOR
  • KMEANS
  • LINEAR_REG
  • LOGISTIC_REG
  • MATRIX_FACTORIZATION
  • TENSORFLOW (modelos importados do TensorFlow)

Exportar formatos de modelos e amostras

A tabela a seguir mostra os formatos finais de exportação para cada tipo de modelo do BigQuery ML, bem como uma amostra dos arquivos que são gravados no bucket do Cloud Storage.

Tipo de modelo Formato do modelo para exportação Amostra de arquivos exportados
AUTOML_CLASSIFIER SavedModel do TensorFlow (TF 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 SavedModel do TensorFlow (TF 1.15 ou superior)
DNN_REGRESSOR
KMEANS
LINEAR_REGRESSOR
LOGISTIC_REG
MATRIX_FACTORIZATION
BOOSTED_TREE_CLASSIFIER Otimizador (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 é para execução local. Consulte Implantação de modelos para mais detalhes.
BOOSTED_TREE_REGRESSOR
TENSORFLOW (importado) TensorFlow SavedModel Exatamente os mesmos arquivos que estavam presentes ao importar o modelo

O modelo não contém as informações sobre o engenheiro de recursos realizadas na instrução SELECT durante o treinamento. Portanto, você precisa converter os dados de entrada manualmente antes de alimentar o modelo exportado.

Limitações

As limitações a seguir são aplicadas na exportação de modelos:

  • Não será possível exportar modelos se qualquer um dos recursos a seguir for usado durante o treinamento:

  • Os modelos exportados para os tipos de modelo AUTOML_REGRESSOR e AUTOML_CLASSIFIER não são compatíveis com a implantação do AI Platform nas previsões on-line.

  • O limite de tamanho do modelo para a exportação do modelo de fatoração de matrizes é 1 GB. O tamanho do modelo é quase proporcional a num_factors, então será possível reduzir num_factors durante o treinamento para diminuir o tamanho do modelo se você atingir o limite.

  • Os recursos relacionados às chaves de criptografia gerenciadas pelo cliente não são compatíveis com a exportação do modelo.

Como exportar modelos do BigQuery ML

Para exportar um modelo:

Console

  1. Abra a página do BigQuery no Console do Cloud.

    Acesse a página do BigQuery

  2. No painel de navegação, na seção Recursos, expanda seu projeto e selecione um conjunto de dados. Localize e clique no modelo que você quer exportar.

  3. No lado direito da janela, clique em Exportar modelo.

    Exportar modelo

  4. Na caixa de diálogo Exportar modelo para o Cloud Storage:

    • Em Selecionar local do Cloud Storage, procure o local do bucket ou da pasta em que você quer exportar o modelo.
    • Clique em Exportar para finalizar a operação.

Para verificar o andamento do job, procure um job de exportação no Histórico de jobs, na parte superior da navegação.

SQL

A instrução EXPORT MODEL permite exportar modelos do BigQuery ML para o Cloud Storage usando a sintaxe de consulta do SQL padrão.

Para exportar um modelo do BigQuery ML no Console do Cloud usando a instrução EXPORT MODEL, siga estas etapas:

  1. No Console do Cloud, abra a página do BigQuery.

    Ir para o BigQuery

  2. Clique em Escrever nova consulta.

  3. No campo Editor de consultas, digite a instrução EXPORT MODEL.

    A consulta a seguir exporta um modelo chamado myproject.mydataset.mymodel para um bucket do Cloud Storage com o URI gs://bucket/path/to/saved_model/.

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

  4. Clique em Executar. Quando a consulta for concluída, o seguinte aparecerá no painel Resultados da consulta: Successfully exported model.

bq

Use o comando bq extractcom a sinalização --model.

(Opcional) Forneça a sinalização --destination_format e escolha o formato do modelo exportado. (Opcional) Forneça a sinalização --location e defina o valor para seu local.

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

Em que:

  • location é o nome do local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. Defina um valor padrão para a unidade usando o arquivo .bigqueryr.
  • destination_format é o formato do modelo exportado: ML_TF_SAVED_MODEL (padrão) ou ML_XGBOOST_BOOSTER.
  • project_id é o ID do projeto;
  • dataset é o nome do conjunto de dados de origem;
  • model é o modelo que você está exportando.
  • bucket é o nome do bucket do Cloud Storage para o qual você está exportando os dados. O conjunto de dados do BigQuery e o bucket do Cloud Storage precisam estar no mesmo local;
  • model_folder é o nome da pasta em que os arquivos de modelo exportados serão gravados.

Exemplos:

O comando a seguir exporta mydataset.mymodel no formato SavedModel do TensorFlow para um bucket do Cloud Storage chamado mymodel_folder.

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

O valor padrão de destination_format é ML_TF_SAVED_MODEL.

O comando a seguir exporta mydataset.mymodel no formato XGBoost Booster para um bucket do Cloud Storage chamado mymodel_folder.

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

API

Para exportar um modelo, crie um job extract e preencha a configuração dele.

(Opcional) Especifique seu local na propriedade location na seção jobReference do recurso job.

  1. Crie um job de extração que aponte para o modelo do BigQuery ML e o destino do Cloud Storage.

  2. Especifique o modelo de origem usando o objeto de configuração sourceModel, que contém os IDs do projeto, do conjunto de dados e do modelo.

  3. A propriedade destination URI(s) precisa ser totalmente qualificada no formato gs://bucket/model_folder.

  4. Especifique o formato de destino definindo a propriedade configuration.extract.destinationFormat. Por exemplo, para exportar um modelo de árvore otimizada, defina essa propriedade com o valor ML_XGBOOST_BOOSTER.

  5. Para verificar o status do job, chame jobs.get(job_id) com o ID do job retornado pela solicitação inicial.

    • status.state = DONE indica que o job foi concluído.
    • Se a propriedade status.errorResult aparecer, isso indica que houve falha na solicitação, e o objeto incluirá informações que descrevem o erro.
    • Se status.errorResult não aparecer, o job foi concluído com sucesso, mesmo se tiver ocorrido erros não fatais. Tais erros são listados na propriedade status.errors do objeto do job retornado.

Observações sobre a API:

  • Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId ao chamar jobs.insert para criar um job. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o ID do job conhecido.

  • Chamar jobs.insert em um determinado ID de job é idempotente, ou seja, mesmo que você repita o processo inúmeras vezes com o mesmo ID, somente uma das operações, no máximo, será bem-sucedida.

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());
    }
  }
}

Implantação do modelo

É possível implantar o modelo exportado no Google Cloud AI Platform e localmente.

Implantação no AI Platform

Formato do modelo para exportação Implantação
SavedModel do Tensorflow (exceto modelos AutoML) Implantar um SavedModel do Tensorflow (versão de ambiente de execução 1.15 ou superior)
SavedModel do Tensorflow (modelos AutoML) Incompatível
XGBoost Booster Rotina de previsão personalizada (versão 1.15 do ambiente de execução)

Observação: como há informações de pré-processamento e pós-processamento salvas nos arquivos exportado, você precisa usar uma Rotina de previsão personalizada para implantar o modelo com os arquivos exportados.

Implantação local

Formato do modelo para exportação Implantação
SavedModel do Tensorflow (exceto modelos AutoML) O SavedModel é um formato padrão que pode ser implantado no contêiner Docker do Tensorflow Serving.

Também é possível aproveitar a execução local da previsão on-line do AI Platform.
SavedModel do Tensorflow (modelos AutoML) Execute o contêiner do AutoML.
XGBoost Booster Para executar modelos do XGBoost Booster localmente, use o arquivo main.py exportado:
  1. Faça o download de todos os arquivos do Cloud Storage para o diretório local.
  2. Descompacte o arquivo predictor.py do xgboost_predictor-0.1.tar.gz no diretório local.
  3. Execute main.py (veja as instruções em main.py).

Formato de saída da previsão

Nesta seção, você verá o formato de saída da previsão para cada tipo de modelo exportado. Todos os tipos de modelo exportado são compatíveis com a previsão em lote, podendo processar várias linhas de entrada por vez. Por exemplo, há duas linhas de entrada em cada um dos exemplos de formato de saída a seguir.

AUTOML_CLASSIFIER

Formato de saída da previsão Amostra de saída

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

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

AUTOML_REGRESSOR

Formato de saída da previsão Amostra de saída

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

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

BOOSTED_TREE_CLASSIFIER

Formato de saída da previsão Amostra de saída

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

Formato de saída da previsão Amostra de saída

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

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

DNN_CLASSIFIER

Formato de saída da previsão Amostra de saída

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

Formato de saída da previsão Amostra de saída

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

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

KMEANS

Formato de saída da previsão Amostra de saída

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

Formato de saída da previsão Amostra de saída

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

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

LOGISTIC_REG

Formato de saída da previsão Amostra de saída

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

Observação: no momento, é possível usar apenas um usuário de entrada e gerar os 50 principais pares (predicted_rating, predicted_item) classificados por predicted_rating em ordem decrescente.

Formato de saída da previsão Amostra de saída

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

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

TENSORFLOW (importado)

Formato de saída da previsão
Igual ao modelo importado

Visualização do modelo XGBoost

Para visualizar as árvores otimizadas, use a API Python plot_tree após a exportação do modelo. Por exemplo, é possível aproveitar o Colab sem instalar as dependências:

  1. Exporte o modelo de árvore otimizada para um bucket do Cloud Storage.
  2. Faça o download do arquivo model.bst a partir do bucket do Cloud Storage.
  3. Em um notebook do Colab, faça o upload do arquivo model.bst para Files.
  4. Execute o seguinte código no 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
    

Este exemplo representa várias árvores (uma árvore por iteração):

Exportar modelo

No momento, não salvamos nomes de recursos no modelo. Portanto, você verá nomes como "f0", "f1" e assim por diante. Você encontra os nomes dos recursos correspondentes no arquivo exportado assets/model_metadata.json que tenham esses nomes (como "f0") como índices.

Permissões necessárias

Para exportar um modelo do BigQuery ML para o Cloud Storage, você precisa ter permissões para acessar o modelo, executar jobs de exportação e gravar os dados no bucket do Cloud Storage.

Permissões do BigQuery

  • Para exportar modelos, é necessário ter, no mínimo, as permissões bigquery.models.export. Os papéis predefinidos do IAM a seguir tem as permissões bigquery.models.export:

    • bigquery.dataViewer
    • bigquery.dataOwner
    • bigquery.dataEditor
    • bigquery.admin
  • Para executar um job de exportação, é necessário ter, no mínimo, as permissões bigquery.jobs.create. Os seguintes papéis predefinidos do IAM tem as permissões bigquery.jobs.create:

    • bigquery.user
    • bigquery.jobUser
    • bigquery.admin

Permissões do Cloud Storage

  • Para gravar dados em um bucket do Cloud Storage, é necessário ter as permissões storage.objects.create. Os papéis predefinidos do IAM a seguir tem as permissões storage.objects.create:

    • storage.objectCreator
    • storage.objectAdmin
    • storage.admin

Para mais informações sobre papéis e permissões do IAM no BigQuery ML, consulte Controle de acesso. Para mais informações sobre papéis no nível do conjunto de dados, consulte Papéis básicos para conjuntos de dados na documentação do BigQuery.

Considerações sobre o local

Ao escolher um local para os dados, leve em consideração os seguintes itens:

  • Defina os buckets do Cloud Storage que receberão os dados exportados.
    • Ao exportar dados, o bucket regional ou multirregional do Cloud Storage precisa estar no mesmo local que o conjunto de dados do BigQuery. Por exemplo, se o conjunto de dados do BigQuery ML estiver no local multirregional UE, o bucket do Cloud Storage que contém os dados a serem exportados precisará estar em um local regional ou multirregional na UE.
    • Se o conjunto de dados estiver em um local regional, seu bucket do Cloud Storage precisará ser um bucket regional no mesmo local. Por exemplo, se o conjunto de dados estiver na região de Tóquio, seu intervalo do Cloud Storage precisará ser um intervalo regional em Tóquio.
    • Exceção: se o seu conjunto de dados estiver no local multirregional dos EUA, será possível exportar dados para um intervalo do Cloud Storage em qualquer local regional ou multirregional.
  • Desenvolver um plano de gerenciamento de dados.
    • Se você escolher um recurso de armazenamento regional, como um conjunto de dados do BigQuery ML ou um bucket do Cloud Storage, será necessário desenvolver um plano para gerenciar geograficamente seus dados.

Para mais informações sobre locais do Cloud Storage, consulte Locais de intervalos na documentação do Cloud Storage.

Como mover dados do BigQuery entre locais

Não é possível alterar o local de um conjunto de dados após a criação, mas tem como fazer uma cópia dele.

Política de cotas

Consulte Jobs de exportação na página "Cotas e limites" para mais informações sobre as cotas para esse tipo de job.

Preço

Não há cobrança pela exportação de modelos do BigQuery ML. No entanto, as exportações estão sujeitas a cotas e limites do BigQuery. Consulte a página de preços do BigQuery para mais informações.

Depois que os dados forem exportados, você será cobrado pelo armazenamento deles no Cloud Storage. Consulte a página de preços do Cloud Storage para mais informações.

A seguir