Importe em lote valores de funcionalidades

A importação em lote permite-lhe importar valores de atributos em massa a partir de uma origem de dados válida. Num pedido de importação em lote, pode importar valores para até 100 caraterísticas de um tipo de entidade. Tenha em atenção que só pode ter uma tarefa de importação em lote em execução por tipo de entidade para evitar colisões.

Num pedido de importação em lote, especifique a localização dos dados de origem e como são mapeados para funcionalidades no seu Feature Store. Uma vez que cada pedido de importação em lote é para um único tipo de entidade, os dados de origem também têm de ser para um único tipo de entidade.

Após a conclusão bem-sucedida da importação, os valores das caraterísticas ficam disponíveis para operações de leitura subsequentes.

Desempenho da tarefa de importação

O Vertex AI Feature Store (antigo) oferece uma importação de elevado débito, mas a latência mínima pode demorar alguns minutos. Cada pedido ao Vertex AI Feature Store (antigo) inicia uma tarefa para concluir o trabalho. Uma tarefa de importação demora alguns minutos a ser concluída, mesmo que esteja a importar um único registo.

Se quiser ajustar o desempenho de uma tarefa, altere as duas variáveis seguintes:

  • O número de nós de publicação online da Feature Store.
  • O número de trabalhadores usados para a tarefa de importação. Os trabalhadores processam e escrevem dados no Feature Store.

O número recomendado de trabalhadores é um trabalhador para cada 10 nós de serviço online no Feature Store. Pode aumentar o valor se a carga de publicação online for baixa. Pode especificar um máximo de 100 trabalhadores. Para mais orientações, consulte o artigo monitorize e ajuste os recursos em conformidade para otimizar a importação em lote.

Se o cluster de publicação online tiver um aprovisionamento insuficiente, a tarefa de importação pode falhar. Em caso de falha, tente novamente o pedido de importação quando a carga de publicação online for baixa ou aumente a quantidade de nós do Feature Store e, em seguida, tente novamente o pedido.

Se o Feature Store não tiver uma loja online (zero nós de publicação online), a tarefa de importação escreve apenas na loja offline e o desempenho da tarefa depende exclusivamente do número de trabalhadores de importação.

Consistência dos dados

Podem ser introduzidas inconsistências se os dados de origem forem modificados durante a importação. Certifique-se de que todas as modificações dos dados de origem estão concluídas antes de iniciar uma tarefa de importação. Além disso, os valores de atributos duplicados podem resultar na publicação de valores diferentes entre pedidos online e em lote. Certifique-se de que tem um valor de funcionalidade para cada par de ID de entidade e carimbo de data/hora.

Se uma operação de importação falhar, o Feature Store pode ter apenas dados parciais, o que pode levar à devolução de valores inconsistentes entre pedidos de fornecimento online e em lote. Para evitar esta inconsistência, tente novamente o mesmo pedido de importação e aguarde até que o pedido seja concluído com êxito.

Valores nulos e matrizes vazias

Durante a importação, o Vertex AI Feature Store (antigo) considera os valores escalares nulos ou as matrizes vazias como valores vazios. Estes incluem valores vazios numa coluna CSV. O Vertex AI Feature Store (antigo) não suporta valores nulos não escalares, como um valor null numa matriz.

Durante a publicação online e a publicação em lote, o Vertex AI Feature Store (antigo) devolve o valor mais recente não nulo ou não vazio da funcionalidade. Se não estiver disponível um valor histórico da funcionalidade, o Vertex AI Feature Store (antigo) devolve null.

Valores NaN

O Vertex AI Feature Store (antigo) suporta valores NaN (Not a Number) em Double e DoubleArray. Durante a importação, pode introduzir NaN no ficheiro CSV de entrada de publicação para representar um valor NaN. Durante a publicação online e a publicação em lote, o Vertex AI Feature Store (antigo) devolve NaN para valores NaN.

Importação em lote

Importe valores em massa para um Feature Store para uma ou mais caraterísticas de um único tipo de entidade.

IU da Web

  1. Na secção Vertex AI da Google Cloud consola, aceda à página Funcionalidades.

    Aceda à página Funcionalidades

  2. Selecione uma região na lista pendente Região.
  3. Na tabela de atributos, veja a coluna Tipo de entidade e encontre o tipo de entidade que contém os atributos para os quais quer importar valores.
  4. Clique no nome do tipo de entidade.
  5. Na barra de ações, clique em Carregar valores.
  6. Para Origem de dados, selecione uma das seguintes opções:
    • Ficheiro CSV do Cloud Storage: selecione esta opção para importar dados de vários ficheiros CSV do Cloud Storage. Especifique o caminho e o nome do ficheiro CSV. Para especificar ficheiros adicionais, clique em Adicionar outro ficheiro.
    • Ficheiro AVRO do Cloud Storage: selecione esta opção para importar dados de um ficheiro AVRO do Cloud Storage. Especifique o caminho e o nome do ficheiro AVRO.
    • Tabela do BigQuery: selecione esta opção para importar dados de uma tabela ou uma vista do BigQuery. Procure e selecione uma tabela ou uma vista a usar, que está no seguinte formato: PROJECT_ID.DATASET_ID.TABLE_ID
  7. Clique em Continuar.
  8. Para Mapear coluna a elementos, especifique que colunas nos seus dados de origem são mapeadas para entidades e elementos no seu Feature Store.
    1. Especifique o nome da coluna nos dados de origem que contém os IDs das entidades.
    2. Para a data/hora, especifique uma coluna de data/hora nos dados de origem ou especifique uma única data/hora associada a todos os valores de atributos que importa.
    3. Na lista de funcionalidades, introduza o nome da coluna de dados de origem que corresponde a cada funcionalidade. Por predefinição, o Vertex AI Feature Store (antigo) assume que o nome da caraterística e o nome da coluna correspondem.
  9. Clique em Carregar.

REST

Para importar valores de funcionalidades para funcionalidades existentes, envie um pedido POST através do método featurestores.entityTypes.importFeatureValues. Tenha em atenção que, se os nomes das colunas de dados de origem e os IDs das funcionalidades de destino forem diferentes, inclua o parâmetro sourceField.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION_ID: região onde o Feature Store é criado. Por exemplo, us-central1.
  • PROJECT_ID: o seu ID do projeto.
  • FEATURESTORE_ID: ID da Feature Store.
  • ENTITY_TYPE_ID: ID do tipo de entidade.
  • ENTITY_SOURCE_COLUMN_ID: ID da coluna de origem que contém os IDs das entidades.
  • FEATURE_TIME_ID: ID da coluna de origem que contém as indicações de tempo das caraterísticas para os valores das caraterísticas.
  • FEATURE_ID: ID de uma funcionalidade existente no Feature Store para importar valores.
  • FEATURE_SOURCE_COLUMN_ID: ID da coluna de origem que contém valores de caraterísticas para as entidades.
  • SOURCE_DATA_DETAILS: a localização dos dados de origem, que também indica o formato, como "bigquerySource": { "inputUri": "bq://test.dataset.sourcetable" } para uma tabela ou uma vista do BigQuery.
  • WORKER_COUNT: o número de trabalhadores a usar para escrever dados no Feature Store.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues

Corpo JSON do pedido: 

{
  "entityIdField": "ENTITY_SOURCE_COLUMN_ID",
  "featureTimeField": "FEATURE_TIME_ID",
  SOURCE_DATA_DETAILS,
  "featureSpecs": [{
    "id": "FEATURE_ID",
    "sourceField": "FEATURE_SOURCE_COLUMN_ID"
  }],
  "workerCount": WORKER_COUNT
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:importFeatureValues" | Select-Object -Expand Content

Deverá ver uma saída semelhante à seguinte. Pode usar o elemento OPERATION_ID na resposta para obter o estado da operação.

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.ImportFeatureValuesOperationMetadata",
    "genericMetadata": {
      "createTime": "2021-03-02T00:04:13.039166Z",
      "updateTime": "2021-03-02T00:04:13.039166Z"
    }
  }
}

Python

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API. 

import datetime
from typing import List, Union

from google.cloud import aiplatform


def import_feature_values_sample(
    project: str,
    location: str,
    entity_type_id: str,
    featurestore_id: str,
    feature_ids: List[str],
    feature_time: Union[str, datetime.datetime],
    gcs_source_uris: Union[str, List[str]],
    gcs_source_type: str,
):

    aiplatform.init(project=project, location=location)

    my_entity_type = aiplatform.featurestore.EntityType(
        entity_type_name=entity_type_id, featurestore_id=featurestore_id
    )

    my_entity_type.ingest_from_gcs(
        feature_ids=feature_ids,
        feature_time=feature_time,
        gcs_source_uris=gcs_source_uris,
        gcs_source_type=gcs_source_type,
    )

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.AvroSource;
import com.google.cloud.aiplatform.v1.EntityTypeName;
import com.google.cloud.aiplatform.v1.FeaturestoreServiceClient;
import com.google.cloud.aiplatform.v1.FeaturestoreServiceSettings;
import com.google.cloud.aiplatform.v1.GcsSource;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesOperationMetadata;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesRequest;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesRequest.FeatureSpec;
import com.google.cloud.aiplatform.v1.ImportFeatureValuesResponse;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ImportFeatureValuesSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String featurestoreId = "YOUR_FEATURESTORE_ID";
    String entityTypeId = "YOUR_ENTITY_TYPE_ID";
    String entityIdField = "YOUR_ENTITY_FIELD_ID";
    String featureTimeField = "YOUR_FEATURE_TIME_FIELD";
    String gcsSourceUri = "YOUR_GCS_SOURCE_URI";
    int workerCount = 2;
    String location = "us-central1";
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    int timeout = 300;
    importFeatureValuesSample(
        project,
        featurestoreId,
        entityTypeId,
        gcsSourceUri,
        entityIdField,
        featureTimeField,
        workerCount,
        location,
        endpoint,
        timeout);
  }

  static void importFeatureValuesSample(
      String project,
      String featurestoreId,
      String entityTypeId,
      String gcsSourceUri,
      String entityIdField,
      String featureTimeField,
      int workerCount,
      String location,
      String endpoint,
      int timeout)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    FeaturestoreServiceSettings featurestoreServiceSettings =
        FeaturestoreServiceSettings.newBuilder().setEndpoint(endpoint).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (FeaturestoreServiceClient featurestoreServiceClient =
        FeaturestoreServiceClient.create(featurestoreServiceSettings)) {
      List<FeatureSpec> featureSpecs = new ArrayList<>();

      featureSpecs.add(FeatureSpec.newBuilder().setId("title").build());
      featureSpecs.add(FeatureSpec.newBuilder().setId("genres").build());
      featureSpecs.add(FeatureSpec.newBuilder().setId("average_rating").build());
      ImportFeatureValuesRequest importFeatureValuesRequest =
          ImportFeatureValuesRequest.newBuilder()
              .setEntityType(
                  EntityTypeName.of(project, location, featurestoreId, entityTypeId).toString())
              .setEntityIdField(entityIdField)
              .setFeatureTimeField(featureTimeField)
              .addAllFeatureSpecs(featureSpecs)
              .setWorkerCount(workerCount)
              .setAvroSource(
                  AvroSource.newBuilder()
                      .setGcsSource(GcsSource.newBuilder().addUris(gcsSourceUri)))
              .build();
      OperationFuture<ImportFeatureValuesResponse, ImportFeatureValuesOperationMetadata>
          importFeatureValuesFuture =
              featurestoreServiceClient.importFeatureValuesAsync(importFeatureValuesRequest);
      System.out.format(
          "Operation name: %s%n", importFeatureValuesFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      ImportFeatureValuesResponse importFeatureValuesResponse =
          importFeatureValuesFuture.get(timeout, TimeUnit.SECONDS);
      System.out.println("Import Feature Values Response");
      System.out.println(importFeatureValuesResponse);
      featurestoreServiceClient.close();
    }
  }
}

Node.js

Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const project = 'YOUR_PROJECT_ID';
// const featurestoreId = 'YOUR_FEATURESTORE_ID';
// const entityTypeId = 'YOUR_ENTITY_TYPE_ID';
// const avroGcsUri = 'AVRO_FILE_IN_THE_GCS_URI';
// const entityIdField = 'ENTITY_ID_FIELD_IN_AVRO';
// const featureTimeField = 'TIMESTAMP_FIELD_IN_AVRO';
// const workerCount = <NO_OF_WORKERS_FOR_INGESTION_JOB>;
// const location = 'YOUR_PROJECT_LOCATION';
// const apiEndpoint = 'YOUR_API_ENDPOINT';
// const timeout = <TIMEOUT_IN_MILLI_SECONDS>;

// Imports the Google Cloud Featurestore Service Client library
const {FeaturestoreServiceClient} = require('@google-cloud/aiplatform').v1;

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: apiEndpoint,
};

// Instantiates a client
const featurestoreServiceClient = new FeaturestoreServiceClient(
  clientOptions
);

async function importFeatureValues() {
  // Configure the entityType resource
  const entityType = `projects/${project}/locations/${location}/featurestores/${featurestoreId}/entityTypes/${entityTypeId}`;

  const avroSource = {
    gcsSource: {
      uris: [avroGcsUri],
    },
  };

  const featureSpecs = [{id: 'age'}, {id: 'gender'}, {id: 'liked_genres'}];

  const request = {
    entityType: entityType,
    avroSource: avroSource,
    entityIdField: entityIdField,
    featureSpecs: featureSpecs,
    featureTimeField: featureTimeField,
    workerCount: Number(workerCount),
  };

  // Import Feature Values Request
  const [operation] = await featurestoreServiceClient.importFeatureValues(
    request,
    {timeout: Number(timeout)}
  );
  const [response] = await operation.promise();

  console.log('Import feature values response');
  console.log('Raw response:');
  console.log(JSON.stringify(response, null, 2));
}
importFeatureValues();

Veja tarefas de importação

Use a consola Google Cloud para ver tarefas de importação em lote num Google Cloud projeto.

IU da Web

  1. Na secção Vertex AI da Google Cloud consola, aceda à página Funcionalidades.

    Aceda à página Funcionalidades

  2. Selecione uma região na lista pendente Região.
  3. Na barra de ações, clique em Ver tarefas de carregamento para listar as tarefas de importação de todas as featurestores.
  4. Clique no ID de uma tarefa de importação para ver os respetivos detalhes, como a origem de dados, o número de entidades de importação e o número de valores de atributos importados.

Substitua dados existentes num Feature Store

Pode reimportar valores para substituir os valores das caraterísticas existentes se ambos tiverem as mesmas datas/horas. Não precisa de eliminar primeiro os valores das funcionalidades existentes. Por exemplo, pode depender de dados de origem subjacentes que foram alterados recentemente. Para manter o featurestore consistente com esses dados subjacentes, importe novamente os valores das funcionalidades. Se tiver datas/horas diferentes, os valores importados são considerados únicos e os valores antigos continuam a existir (não são substituídos).

Para garantir a consistência entre os pedidos de publicação online e em lote, aguarde até que a tarefa de importação esteja concluída antes de fazer pedidos de publicação.

Preencha dados do histórico

Se estiver a preencher dados, em que importa valores de atributos anteriores, desative a publicação online para a tarefa de importação. A publicação online destina-se apenas à publicação dos valores das funcionalidades mais recentes, que o preenchimento não inclui. A desativação da publicação online é útil porque elimina qualquer carga nos nós de publicação online e aumenta o débito para a tarefa de importação, o que pode diminuir o tempo de conclusão.

Pode desativar a publicação online para tarefas de importação quando usa a API ou as bibliotecas de cliente. Para mais informações, consulte o campo disableOnlineServing do método importFeatureValue.

O que se segue?