Criar um grupo de elementos

Um grupo de recursos é um recurso do Registro de recursos associado a uma tabela ou visualização do BigQuery que contém seus dados de recursos. Um grupo de recursos pode conter vários recursos, em que cada um está associado a uma coluna na fonte de dados de recursos. Se você quiser registrar sua fonte de dados de recursos no registro de recursos, crie um grupo de recursos e então adicione recursos a ele.

Depois de criar um grupo de recursos e associar a fonte de dados do BigQuery, você pode criar recursos associados às colunas na fonte de dados. Embora seja opcional associar uma fonte de dados ao criar um grupo de recursos, é necessário associar uma tabela ou visualização do BigQuery antes de criar recursos nesse grupo. Cada recurso corresponde a uma coluna na fonte de dados associada ao grupo de recursos.

Por que usar grupos e atributos?

O registro da fonte de dados de recursos é opcional. No entanto, é necessário registrar os dados de recursos criando grupos de recursos e atributos nos seguintes cenários:

  • Usar dados históricos no formato de série temporal para treinar um modelo: se a fonte de dados de recursos contiver dados de recursos mais recentes e históricos com vários registros de recursos para o mesmo ID da entidade, formate esses dados como uma série temporal adicionando a coluna feature_timestamp. Nesse cenário, é necessário registrar a fonte de dados usando grupos de recursos e atributos. Em seguida, é possível disponibilizar recursos da seguinte maneira:

    • Use a veiculação on-line para disponibilizar os valores de atributos mais recentes com base no carimbo de data/hora para fazer previsões em tempo real.

    • Use a disponibilização off-line para disponibilizar os valores de atributos mais recentes e históricos para treinar um modelo.

  • Agregar recursos de várias fontes: use grupos de recursos para agregar colunas específicas de várias fontes de dados do BigQuery ao criar uma instância de visualização de recursos.

  • Disponibilizar valores de atributos nulos: durante a veiculação on-line, se você quiser disponibilizar apenas os valores de atributos mais recentes, incluindo valores nulos, registre sua fonte de dados de recursos criando grupos de recursos com o parâmetro dense definido como true.

  • Usar a sincronização contínua de dados nas visualizações de recursos: o registro de recursos é um pré-requisito para usar a sincronização contínua de dados nas visualizações de recursos.

  • Monitorar recursos em busca de anomalias: é necessário registrar os recursos se você quiser configurar o monitoramento de recursos para extrair estatísticas de recursos e detectar desvios de recursos.

Quando não usar grupos e atributos

Se você quiser disponibilizar embeddings da sua fonte de dados de recursos, não registre a fonte de dados criando grupos de recursos e atributos. Nesse cenário, é necessário configurar a veiculação on-line associando diretamente a tabela do BigQuery ou visualização às visualizações de recursos.

Para mais informações sobre como configurar a veiculação on-line sem registrar a fonte de dados de recursos, consulte Criar uma visualização de recursos de uma fonte do BigQuery.

Controle o acesso

É possível controlar o acesso a um grupo de recursos nos seguintes níveis:

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

  • Controlar o acesso à fonte de dados do BigQuery: por padrão, um grupo de recursos usa a conta de serviço padrão configurada para o projeto. O Vertex AI Feature Store atribui o papel de Leitor de dados do BigQuery do Identity and Access Management (IAM) a essa conta de serviço. Isso permite que qualquer usuário com permissão para criar um grupo de recursos no projeto acesse a fonte de dados de recursos no BigQuery. Para restringir o acesso à fonte de dados do BigQuery ou conceder acesso a outros usuários, é possível configurar o grupo de recursos para usar a própria conta de serviço dedicada. O Vertex AI Feature Store gera um endereço de e-mail exclusivo da conta de serviço para cada grupo de recursos configurado para ter uma conta de serviço dedicada.

Antes de começar

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

  • Verifique se há pelo menos uma instância de loja on-line criada no projeto, mesmo que você queira criar uma nova instância de loja on-line. Se você estiver usando um novo projeto, então crie uma instância de loja on-line antes de criar o grupo de recursos.

  • Formate os dados de recursos na tabela do BigQuery ou visualização do BigQuery para obedecer às diretrizes de preparação da fonte de dados.

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

  • Autentique-se na Gemini Enterprise Agent Platform, a menos que já tenha feito isso.

    Selecione a guia para como planeja usar as amostras nesta página:

    Console

    Quando você usa o Google Cloud console para acessar Google Cloud serviços e APIs, não é necessário configurar a autenticação.

    Python

    Para usar os exemplos do Python desta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

    1. Instale a Google Cloud CLI.

    2. Se você estiver usando um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

    3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

      gcloud auth application-default login

      Não é necessário fazer isso se você estiver usando o Cloud Shell.

      Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

    Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

    REST

    Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a Google Cloud CLI.

      Se você estiver usando um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Criar um grupo de recursos para registrar uma fonte de dados de recursos

Use o exemplo a seguir para criar um grupo de recursos e associar uma fonte de dados de recursos, como uma tabela ou visualização do BigQuery.

Console

Use as instruções a seguir para criar um grupo de recursos usando o Google Cloud console:

  1. Na seção Agent Platform do Google Cloud console, acesse a página Feature Store.

    Acessar a página da Feature Store

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

  3. Especifique o Nome do grupo de recursos.

  4. Opcional: para adicionar rótulos, clique em Adicionar rótulo e especifique o nome e o valor do rótulo. É possível adicionar vários rótulos a um grupo de recursos.

  5. No campo Caminho do BigQuery, clique em Procurar para selecionar a tabela ou visualização de origem do BigQuery a ser associada ao grupo de recursos.

  6. Na lista Coluna de ID da entidade, selecione as colunas de ID da entidade na tabela ou visualização de origem do BigQuery.

    Observação: isso é opcional se a tabela ou visualização de origem do BigQuery tiver uma coluna chamada entity_id. Nesse caso, se você não selecionar uma coluna de ID da entidade, o grupo de recursos usará a coluna entity_id como a coluna de ID da entidade padrão.

  7. Clique em Continuar.

  8. No painel Registrar, clique em uma das seguintes opções para indicar se você quer adicionar recursos ao novo grupo de recursos:

    • Incluir todas as colunas da tabela do BigQuery: crie recursos no grupo de recursos para todas as colunas na tabela ou visualização de origem do BigQuery.

    • Inserir recursos manualmente: crie recursos com base em colunas específicas na origem do BigQuery. Para cada recurso, insira um Nome do recurso e clique no nome da coluna de origem do BigQuery correspondente na lista.

      Para adicionar mais elementos, clique em Adicionar outro recurso.

    • Criar um grupo de recursos vazio: cria o grupo de recursos sem adicionar funcionalidades a ele.

  9. Clique em Criar.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da 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 projeto.
  • location: região em que você quer criar o grupo de recursos, como us-central1.
  • feature_group_id: o nome do novo grupo de recursos que você quer criar.
  • bq_table_uri: URI da tabela de origem ou visualização do BigQuery que você quer registrar para o grupo de recursos.
  • entity_id_columns: os nomes das colunas que contêm os IDs das entidades. É possível especificar uma ou várias colunas.
    • Para especificar apenas uma coluna de IDs das entidades, especifique o nome da coluna no seguinte formato:
      "entity_id_column_name".
    • Para especificar várias colunas de IDs das 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 uma solicitação POST usando o método featureGroups.create.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION_ID: região em que você quer criar o grupo de recursos, como us-central1.
  • SERVICE_AGENT_TYPE: opcional. Configuração da conta de serviço para o grupo de recursos. Para usar uma conta de serviço dedicada para o grupo de recursos, insira SERVICE_AGENT_TYPE_FEATURE_GROUP.
  • PROJECT_ID: o ID do projeto.
  • ENTITY_ID_COLUMNS: os nomes das colunas que contêm os IDs das entidades. É possível especificar uma ou várias colunas.
    • Para especificar apenas uma coluna de IDs das entidades, especifique o nome da coluna no seguinte formato:
      "entity_id_column_name".
    • Para especificar várias colunas ID das 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 recursos que você quer criar.
  • BIGQUERY_SOURCE_URI: URI da tabela de origem ou visualização do BigQuery que você quer registrar para o grupo de recursos.
  • TIMESTAMP_COLUMN: opcional. Especifique o nome da coluna que contém os carimbos de data/hora de recursos na tabela ou visualização de origem do BigQuery.
    É necessário especificar o nome da coluna de carimbo de data/hora somente se os dados forem formatados como uma série temporal e a coluna que contém os carimbos de data/hora de recursos não for nomeada feature_timestamp.
  • STATIC_DATA_SOURCE: opcional. Insira true se os dados não estiverem formatados como uma série temporal. A configuração padrão é false.
  • DENSE: opcional. Indique como o Vertex AI Feature Store processa valores nulos ao disponibilizar dados de visualizações de recursos associadas ao grupo de recursos:
    • false: essa é a configuração padrão. O Vertex AI Feature Store disponibiliza apenas os valores de atributos não nulos mais recentes. Se o valor mais recente de um recurso for nulo, o Vertex AI Feature Store disponibilizará o valor histórico não nulo mais recente. No entanto, se os valores atuais e históricos desse recurso forem nulos, o Vertex AI Feature Store disponibilizará o valor nulo como o valor do recurso.
    • true: para visualizações de recursos com sincronização de dados programada, o Vertex AI Feature Store disponibiliza apenas os valores de atributos mais recentes, incluindo valores nulos. Para visualizações de recursos com sincronização contínua de dados, o Vertex AI Feature Store disponibiliza apenas os valores de atributos não nulos mais recentes. No entanto, se os valores atuais e históricos do recurso forem nulos, o Vertex AI Feature Store disponibilizará o valor nulo como o valor do recurso. Para mais informações sobre os tipos de sincronização de dados e como configurar o tipo de sincronização de dados em uma visualização de recursos, consulte Sincronizar os dados em uma 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 da solicitação: 

{
  "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 a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$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

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
    }
  }
}

A seguir