Crie um grupo de funcionalidades

Um grupo de funcionalidades é um recurso do registo de funcionalidades associado a uma tabela ou uma vista do BigQuery que contém os seus dados de funcionalidades. Um grupo de funcionalidades pode conter várias funcionalidades, em que cada funcionalidade está associada a uma coluna na origem de dados de funcionalidades. Se quiser registar a sua origem de dados de caraterísticas no registo de caraterísticas, crie um grupo de caraterísticas e, em seguida, adicione caraterísticas ao mesmo.

Depois de criar um grupo de funcionalidades e associar a origem de dados do BigQuery, pode criar funcionalidades associadas às colunas na origem de dados. Tenha em atenção que, embora seja opcional associar uma origem de dados durante a criação de um grupo de funcionalidades, tem de associar uma tabela ou uma vista do BigQuery antes de criar funcionalidades nesse grupo de funcionalidades. Cada funcionalidade corresponde a uma coluna na origem de dados associada ao grupo de funcionalidades.

Por que motivo deve usar grupos de funcionalidades e funcionalidades?

O registo da origem de dados de recursos é opcional. No entanto, tem de registar os dados de recursos criando grupos de recursos e recursos nos seguintes cenários:

  • Use dados do histórico no formato de séries cronológicas para preparar um modelo: se a origem de dados das caraterísticas contiver os dados das caraterísticas mais recentes, bem como os dados das caraterísticas do histórico, com vários registos de caraterísticas para o mesmo ID da entidade, formate estes dados como uma série cronológica adicionando a coluna feature_timestamp. Neste cenário, tem de registar a origem de dados através de grupos de funcionalidades e funcionalidades. Em seguida, pode apresentar funcionalidades da seguinte forma:

    • Use a publicação online para publicar os valores das funcionalidades mais recentes com base na data/hora para fazer previsões em tempo real.

    • Use a publicação offline para publicar os valores das funcionalidades mais recentes, bem como os do histórico, para formar um modelo.

  • Agregue funcionalidades de várias origens: use grupos de funcionalidades para agregar colunas específicas de várias origens de dados do BigQuery quando criar uma instância de visualização de funcionalidades.

  • Publicar valores de caraterísticas nulos: durante a publicação online, se quiser publicar apenas os valores de caraterísticas mais recentes, incluindo valores nulos, registe a sua origem de dados com caraterísticas criando grupos de caraterísticas com o parâmetro dense definido como true.

  • Use a sincronização contínua de dados nas vistas de atributos: o registo dos atributos é um pré-requisito para usar a sincronização contínua de dados nas vistas de atributos.

  • Monitorize funcionalidades quanto a anomalias: tem de registar as suas funcionalidades se quiser configurar a monitorização de funcionalidades para obter estatísticas de funcionalidades e detetar a variação das funcionalidades.

Quando não usar grupos de funcionalidades e funcionalidades

Se quiser publicar incorporações a partir da sua origem de dados de caraterísticas, não registe a origem de dados criando grupos de caraterísticas e caraterísticas. Neste cenário, tem de configurar a publicação online associando diretamente a tabela ou a vista do BigQuery às vistas de propriedades.

Para mais informações sobre a configuração da publicação online sem registar a origem de dados de atributos, consulte o artigo Crie uma vista de atributos a partir de uma origem do BigQuery.

Controle o acesso

Pode controlar o acesso a um grupo de funcionalidades nos seguintes níveis:

  • Controlar o acesso ao recurso FeatureGroup: para controlar o acesso a um grupo de funcionalidades para um indivíduo, um grupo Google, um domínio ou uma conta de serviço específicos, configure uma política de IAM para o grupo de funcionalidades.

  • Controlar o acesso à origem de dados do BigQuery: por predefinição, um grupo de funcionalidades usa a conta de serviço predefinida configurada para o projeto. O Vertex AI Feature Store atribui a função de gestão de identidade e de acesso (IAM) de visualizador de dados do BigQuery a esta conta de serviço. Isto permite que qualquer utilizador com autorização para criar um grupo de funcionalidades no projeto aceda à origem de dados de funcionalidades no BigQuery. Para restringir o acesso à origem de dados do BigQuery ou conceder acesso a utilizadores adicionais, pode configurar o seu grupo de funcionalidades para usar a sua própria conta de serviço dedicada. O Vertex AI Feature Store gera um endereço de email da conta de serviço exclusivo para cada grupo de funcionalidades configurado para ter uma conta de serviço dedicada.

Antes de começar

Antes de criar um grupo de funcionalidades, conclua os seguintes pré-requisitos:

  • Certifique-se de que existe, pelo menos, uma instância da loja online criada no seu projeto, mesmo que queira criar uma nova instância da loja online. Se estiver a usar um novo projeto, crie uma instância da loja online antes de criar o grupo de funcionalidades.

  • Formate os dados das funcionalidades na tabela ou na vista do BigQuery de acordo com as diretrizes de preparação de origens de dados.

  • Verifique se a sua origem de dados do BigQuery contém, pelo menos, uma coluna de ID da entidade com valores string ou int.

  • Autentique o Vertex AI, a menos que já o tenha feito.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    Python

    Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Set up authentication for a local development environment.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

    Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.

Crie um grupo de funcionalidades para registar uma origem de dados de funcionalidades

Use os exemplos seguintes para criar um grupo de funcionalidades e associar uma origem de dados de funcionalidades, como uma tabela ou uma vista do BigQuery.

Consola

Siga as instruções abaixo para criar um grupo de funcionalidades através da Google Cloud consola:

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

    Aceda à página da Feature Store

  2. Na secção Grupos de funcionalidades, clique em Criar para abrir o painel Informações básicas na página Criar grupo de funcionalidades.

  3. Especifique o Nome do grupo de funcionalidades.

  4. Opcional: para adicionar etiquetas, clique em Adicionar etiqueta e especifique o nome e o valor da etiqueta. Pode adicionar várias etiquetas a um grupo de funcionalidades.

  5. No campo Caminho do BigQuery, clique em Procurar para selecionar a tabela de origem do BigQuery ou a vista a associar ao grupo de funcionalidades.

  6. Na lista da coluna ID da entidade, selecione as colunas de ID da entidade da tabela ou vista de origem do BigQuery.

    Tenha em atenção que isto é opcional se a tabela ou a vista de origem do BigQuery tiver uma coluna denominada entity_id. Nesse caso, se não selecionar uma coluna de ID de entidade, o grupo de funcionalidades usa a coluna entity_id como a coluna de ID de entidade predefinida.

  7. Clique em Continuar.

  8. No painel Registar, clique numa das seguintes opções para indicar se quer adicionar funcionalidades ao novo grupo de funcionalidades:

    • Incluir todas as colunas da tabela do BigQuery: crie funcionalidades no grupo de funcionalidades para todas as colunas na tabela ou vista de origem do BigQuery.

    • Introduzir manualmente as suas caraterísticas: crie caraterísticas com base em colunas específicas na origem do BigQuery. Para cada funcionalidade, introduza um Nome da funcionalidade e clique no nome da coluna de origem do BigQuery correspondente na lista.

      Para adicionar mais funcionalidades, clique em Adicionar outra funcionalidade.

    • Crie um grupo de funcionalidades vazio: crie o grupo de funcionalidades sem adicionar funcionalidades ao mesmo.

  9. Clique em Criar.

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. 


from google.cloud import aiplatform
from vertexai.resources.preview import feature_store
from typing import List


def create_feature_group_sample(
    project: str,
    location: str,
    feature_group_id: str,
    bq_table_uri: str,
    entity_id_columns: List[str],
):
    aiplatform.init(project=project, location=location)
    fg = feature_store.FeatureGroup.create(
        name=feature_group_id,
        source=feature_store.utils.FeatureGroupBigQuerySource(
            uri=bq_table_uri, entity_id_columns=entity_id_columns
        ),
    )
    return fg
  • project: o ID do seu projeto.
  • location: região onde quer criar o grupo de funcionalidades, como us-central1.
  • feature_group_id: o nome do novo grupo de funcionalidades que quer criar.
  • bq_table_uri: URI da tabela ou vista de origem do BigQuery que quer registar para o grupo de funcionalidades.
  • entity_id_columns: os nomes das colunas que contêm os IDs das entidades. Pode especificar uma ou várias colunas.
    • Para especificar apenas uma coluna de ID de entidade, especifique o nome da coluna no seguinte formato:
      "entity_id_column_name".
    • Para especificar várias colunas de ID de entidades, especifique os nomes das colunas no seguinte formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].

REST

Para criar um recurso FeatureGroup, envie um pedido POST através do método featureGroups.create.

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

  • LOCATION_ID: região onde quer criar o grupo de funcionalidades, como us-central1.
  • SERVICE_AGENT_TYPE: opcional. Configuração da conta de serviço para o grupo de funcionalidades. Para usar uma conta de serviço dedicada para o grupo de funcionalidades, introduza SERVICE_AGENT_TYPE_FEATURE_GROUP.
  • PROJECT_ID: o ID do seu projeto.
  • ENTITY_ID_COLUMNS: os nomes das colunas que contêm os IDs das entidades. Pode especificar uma ou várias colunas.
    • Para especificar apenas uma coluna de ID de entidade, especifique o nome da coluna no seguinte formato:
      "entity_id_column_name".
    • Para especificar várias colunas de ID de entidades, especifique os nomes das colunas no seguinte formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].
  • FEATUREGROUP_NAME: o nome do novo grupo de funcionalidades que quer criar.
  • BIGQUERY_SOURCE_URI: URI da tabela ou vista de origem do BigQuery que quer registar para o grupo de funcionalidades.
  • TIMESTAMP_COLUMN: opcional. Especifique o nome da coluna que contém as indicações de tempo das caraterísticas na tabela ou vista de origem do BigQuery.
    Só tem de especificar o nome da coluna de indicação de tempo se os dados estiverem formatados como uma série cronológica e a coluna que contém as indicações de tempo das caraterísticas não se chamar feature_timestamp.
  • STATIC_DATA_SOURCE: opcional. Introduza true se os dados não estiverem formatados como uma série cronológica. A predefinição é false.
  • DENSE: opcional. Indique como o Vertex AI Feature Store trata os valores nulos durante a publicação de dados de vistas de recursos associadas ao grupo de recursos:
    • false: esta é a predefinição. O Vertex AI Feature Store apenas fornece os valores de caraterísticas não nulos mais recentes. Se o valor mais recente de uma funcionalidade for nulo, o Vertex AI Feature Store disponibiliza o valor histórico não nulo mais recente. No entanto, se os valores atuais e históricos dessa funcionalidade forem nulos, o Vertex AI Feature Store apresenta nulo como o valor da funcionalidade.
    • true—Para vistas de funcionalidades com sincronização de dados agendada, o Vertex AI Feature Store disponibiliza apenas os valores de funcionalidades mais recentes, incluindo valores nulos. Para vistas de funcionalidades com sincronização de dados contínua, o Vertex AI Feature Store apenas disponibiliza os valores de funcionalidades mais recentes que não sejam nulos. No entanto, se os valores atuais e históricos da funcionalidade forem nulos, o Vertex AI Feature Store apresenta nulo como o valor da funcionalidade. Para mais informações sobre os tipos de sincronização de dados e como configurar o tipo de sincronização de dados numa visualização de recursos, consulte Sincronize os dados numa visualização de recursos.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME

Corpo JSON do pedido: 

{
  "service_agent_type": "SERVICE_AGENT_TYPE",
  "big_query": {
    "entity_id_columns": "ENTITY_ID_COLUMNS",
    "big_query_source": {
      "input_uri": "BIGQUERY_SOURCE_URI",
    }
    "time_series": {
      "timestamp_column": ""TIMESTAMP_COLUMN"",
    },
    "static_data_source": STATIC_DATA_SOURCE,
    "dense": DENSE
  }
}

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/featureGroups?feature_group_id=FEATUREGROUP_NAME"

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/featureGroups?feature_group_id=FEATUREGROUP_NAME" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateFeatureGroupOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-09-18T03:00:13.060636Z",
      "updateTime": "2023-09-18T03:00:13.060636Z"
    }
  }
}

O que se segue?