Creare un gruppo di funzionalità

Un gruppo di caratteristiche è una risorsa del registro delle caratteristiche associata a una tabella o vista BigQuery contenente i dati delle caratteristiche. Un gruppo di caratteristiche può contenere più caratteristiche, dove ogni caratteristica è associata a una colonna nell'origine dei dati delle caratteristiche. Se vuoi registrare l'origine dati delle caratteristiche nel Registro di caratteristiche, crea un gruppo di caratteristiche e poi aggiungi le caratteristiche.

Dopo aver creato un gruppo di caratteristiche e associato l'origine dati BigQuery, puoi creare caratteristiche associate alle colonne dell'origine dati. Tieni presente che, sebbene sia facoltativo associare un'origine dati durante la creazione di un gruppo di caratteristiche, devi associare una tabella o una vista BigQuery prima di creare caratteristiche all'interno di quel gruppo di caratteristiche. Ogni funzionalità corrisponde a una colonna nell'origine dati associata al gruppo di funzionalità.

Perché utilizzare gruppi di caratteristiche e caratteristiche?

La registrazione dell'origine dati delle caratteristiche è facoltativa. Tuttavia, devi registrare i dati delle caratteristiche creando gruppi di caratteristiche e caratteristiche nei seguenti scenari:

  • Utilizza i dati storici in formato di serie temporale per addestrare un modello: se l'origine dati delle funzionalità contiene i dati delle funzionalità più recenti e storici con più record di funzionalità per lo stesso ID entità, formatta questi dati come una serie temporale aggiungendo la colonna feature_timestamp. In questo scenario, devi registrare l'origine dati utilizzando gruppi di caratteristiche e caratteristiche. Puoi quindi mostrare le funzionalità nel seguente modo:

    • Utilizza la pubblicazione online per pubblicare i valori delle caratteristiche più recenti in base al timestamp per fare previsioni in tempo reale.

    • Utilizza la pubblicazione offline per pubblicare i valori delle caratteristiche più recenti e storici per addestrare un modello.

  • Aggrega le caratteristiche da più origini: utilizza i gruppi di caratteristiche per aggregare colonne specifiche da più origini dati BigQuery quando crei un'istanza della vista delle caratteristiche.

  • Pubblica valori delle caratteristiche null: durante la pubblicazione online, se vuoi pubblicare solo i valori delle caratteristiche più recenti, inclusi i valori null, registra l'origine dati delle caratteristiche creando gruppi di caratteristiche con il parametro dense impostato su true.

  • Utilizza la sincronizzazione continua dei dati nelle visualizzazioni delle funzionalità: la registrazione delle funzionalità è un prerequisito per l'utilizzo della sincronizzazione continua dei dati nelle visualizzazioni delle funzionalità.

  • Monitorare le caratteristiche per rilevare anomalie: devi registrare le caratteristiche se vuoi configurare il monitoraggio delle caratteristiche per recuperare le statistiche sulle caratteristiche e rilevare la deviazione delle caratteristiche.

Quando non utilizzare gruppi di funzionalità e funzionalità

Se vuoi mostrare incorporamenti dall'origine dati delle funzionalità, non registrare l'origine dati creando gruppi di funzionalità e funzionalità. In questo scenario, devi configurare la pubblicazione online associando direttamente la tabella o la vista BigQuery alle tue viste delle funzionalità.

Per ulteriori informazioni sulla configurazione della pubblicazione online senza registrare l'origine dati delle funzionalità, consulta Creare una visualizzazione delle funzionalità da un'origine BigQuery.

Controllare l'accesso

Puoi controllare l'accesso per un gruppo di funzionalità ai seguenti livelli:

  • Controlla l'accesso alla risorsa FeatureGroup: per controllare l'accesso a un gruppo di funzionalità per un individuo, un gruppo Google, un dominio o un account di servizio specifici, configura un criterio IAM per il gruppo di funzionalità.

  • Controlla l'accesso all'origine dati BigQuery: per impostazione predefinita, un gruppo di funzionalità utilizza l'account di servizio predefinito configurato per il progetto. Vertex AI Feature Store assegna il ruolo Data Viewer di BigQuery Identity and Access Management (IAM) a questo account di servizio. In questo modo, qualsiasi utente con l'autorizzazione per creare un gruppo di funzionalità nel progetto può accedere all'origine dati delle funzionalità in BigQuery. Per limitare l'accesso all'origine dati BigQuery o per concedere l'accesso a utenti aggiuntivi, puoi configurare il gruppo di funzionalità in modo che utilizzi un proprio account di servizio dedicato. Vertex AI Feature Store genera un indirizzo email univoco dell'account di servizio per ogni gruppo di funzionalità configurato per avere un account di servizio dedicato.

Prima di iniziare

Prima di creare un gruppo di funzionalità, completa i seguenti prerequisiti:

  • Assicurati che nel tuo progetto sia stata creata almeno un'istanza di negozio online, anche se vuoi crearne una nuova. Se utilizzi un nuovo progetto, crea un'istanza del negozio online prima di creare il gruppo di funzionalità.

  • Formatta i dati delle caratteristiche nella tabella o nella vista BigQuery in modo che siano conformi alle linee guida per la preparazione dell'origine dati.

  • Verifica che l'origine dati BigQuery contenga almeno una colonna ID entità con valori string o int.

  • Autenticati su Vertex AI, a meno che tu non l'abbia già fatto.

    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

    Per utilizzare gli esempi di Python questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le credenziali predefinite dell'applicazione con le tue credenziali utente.

      Installa Google Cloud CLI.

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

      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.

    Per ulteriori informazioni, vedi Set up authentication for a local development environment.

    REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI.

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticarsi per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud .

Creare un gruppo di caratteristiche per registrare un'origine dati delle caratteristiche

Utilizza gli esempi seguenti per creare un gruppo di caratteristiche e associare un'origine dati delle caratteristiche, ad esempio una tabella o una vista BigQuery.

Console

Utilizza le seguenti istruzioni per creare un gruppo di funzionalità utilizzando la console Google Cloud :

  1. Nella sezione Vertex AI della console Google Cloud , vai alla pagina Feature Store.

    Vai alla pagina Feature Store

  2. Nella sezione Gruppi di funzionalità, fai clic su Crea per aprire il riquadro Informazioni di base nella pagina Crea gruppo di funzionalità.

  3. Specifica il nome del gruppo di funzionalità.

  4. (Facoltativo) Per aggiungere etichette, fai clic su Aggiungi etichetta e specifica il nome e il valore dell'etichetta. Puoi aggiungere più etichette a un gruppo di funzionalità.

  5. Nel campo Percorso BigQuery, fai clic su Sfoglia per selezionare la tabella o la vista di origine BigQuery da associare al gruppo di caratteristiche.

  6. Nell'elenco Colonna ID entità, seleziona le colonne ID entità dalla tabella o dalla visualizzazione di origine BigQuery.

    Tieni presente che questo campo è facoltativo se la tabella o la vista di origine BigQuery contiene una colonna denominata entity_id. In questo caso, se non selezioni una colonna ID entità, il gruppo di funzionalità utilizza la colonna entity_id come colonna ID entità predefinita.

  7. Fai clic su Continua.

  8. Nel riquadro Registra, fai clic su una delle seguenti opzioni per indicare se vuoi aggiungere funzionalità al nuovo gruppo di funzionalità:

    • Includi tutte le colonne della tabella BigQuery: crea caratteristiche all'interno del gruppo di caratteristiche per tutte le colonne della tabella o della vista di origine BigQuery.

    • Inserisci manualmente le funzionalità: crea funzionalità in base a colonne specifiche nell'origine BigQuery. Per ogni caratteristica, inserisci un Nome della caratteristica e fai clic sul nome della colonna di origine BigQuery corrispondente nell'elenco.

      Per aggiungere altre funzionalità, fai clic su Aggiungi un'altra funzionalità.

    • Crea un gruppo di caratteristiche vuoto: crea il gruppo di caratteristiche senza aggiungerne.

  9. Fai clic su Crea.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 


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: il tuo ID progetto.
  • location: la regione in cui vuoi creare il gruppo di funzionalità, ad esempio us-central1.
  • feature_group_id: il nome del nuovo gruppo di funzionalità che vuoi creare.
  • bq_table_uri: URI della tabella o della vista di origine BigQuery che vuoi registrare per il gruppo di funzionalità.
  • entity_id_columns: i nomi delle colonne contenenti gli ID entità. Puoi specificare una o più colonne.
    • Per specificare una sola colonna ID entità, specifica il nome della colonna nel seguente formato:
      "entity_id_column_name".
    • Per specificare più colonne ID entità, specifica i nomi delle colonne nel seguente formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].

REST

Per creare una risorsa FeatureGroup, invia una richiesta POST utilizzando il metodo featureGroups.create.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION_ID: la regione in cui vuoi creare il gruppo di funzionalità, ad esempio us-central1.
  • SERVICE_AGENT_TYPE: (Facoltativo) Configurazione del service account per il gruppo di funzionalità. Per utilizzare un account di servizio dedicato per il gruppo di funzionalità, inserisci SERVICE_AGENT_TYPE_FEATURE_GROUP.
  • PROJECT_ID: il tuo ID progetto.
  • ENTITY_ID_COLUMNS: i nomi delle colonne contenenti gli ID entità. Puoi specificare una o più colonne.
    • Per specificare una sola colonna ID entità, specifica il nome della colonna nel seguente formato:
      "entity_id_column_name".
    • Per specificare più colonne ID entità, specifica i nomi delle colonne nel seguente formato:
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].
  • FEATUREGROUP_NAME: il nome del nuovo gruppo di funzionalità che vuoi creare.
  • BIGQUERY_SOURCE_URI: URI della tabella o della vista di origine BigQuery che vuoi registrare per il gruppo di funzionalità.
  • TIMESTAMP_COLUMN: (Facoltativo) Specifica il nome della colonna contenente i timestamp delle funzionalità nella tabella o nella vista di origine BigQuery.
    Devi specificare il nome della colonna timestamp solo se i dati sono formattati come serie temporale e la colonna contenente i timestamp delle funzionalità non è denominata feature_timestamp.
  • STATIC_DATA_SOURCE: (Facoltativo) Inserisci true se i dati non sono formattati come serie temporale. L'impostazione predefinita è false.
  • DENSE: (Facoltativo) Indica in che modo Vertex AI Feature Store gestisce i valori null durante la pubblicazione dei dati dalle visualizzazioni delle caratteristiche associate al gruppo di caratteristiche:
    • false: questa è l'impostazione predefinita. Vertex AI Feature Store mostra solo i valori delle caratteristiche non nulli più recenti. Se l'ultimo valore di una caratteristica è null, Vertex AI Feature Store pubblica il valore storico non nullo più recente. Tuttavia, se i valori attuali e storici di questa funzionalità sono null, Vertex AI Feature Store restituisce null come valore della funzionalità.
    • true: per le visualizzazioni delle caratteristiche con sincronizzazione dei dati pianificata, Vertex AI Feature Store pubblica solo i valori delle caratteristiche più recenti, inclusi i valori nulli. Per le visualizzazioni delle funzionalità con sincronizzazione continua dei dati, Vertex AI Feature Store mostra solo i valori delle funzionalità non nulli più recenti. Tuttavia, se i valori attuali e storici della funzionalità sono nulli, Vertex AI Feature Store restituisce null come valore della funzionalità. Per ulteriori informazioni sui tipi di sincronizzazione dei dati e su come configurare il tipo di sincronizzazione dei dati in una vista delle funzionalità, vedi Sincronizzare i dati in una vista delle funzionalità.

Metodo 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 della richiesta: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo 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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Passaggi successivi