Creare un gruppo di funzionalità

Un gruppo di caratteristiche è una risorsa del registro di 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 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 aver associato l'origine dati BigQuery, puoi creare caratteristiche associate alle colonne nell'origine dati. Tieni presente che, sebbene l'associazione di un'origine dati durante la creazione di un gruppo di caratteristiche sia facoltativa, devi associare una tabella o una vista BigQuery prima di creare caratteristiche all'interno di quel gruppo di caratteristiche. Ogni caratteristica corrisponde a una colonna nell'origine dati associata al gruppo di caratteristiche.

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:

  • Utilizzare i dati storici in formato di serie temporali per addestrare un modello: se l'origine dati delle caratteristiche contiene i dati delle caratteristiche più recenti e storici con più record di caratteristiche 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 pubblicare le caratteristiche come segue:

    • Utilizza l'erogazione online per erogare 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.

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

  • Erogare valori delle caratteristiche null: durante l'erogazione online, se vuoi erogare 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.

  • Utilizzare la sincronizzazione continua dei dati nelle viste delle caratteristiche: la registrazione delle caratteristiche è un prerequisito per l'utilizzo della sincronizzazione continua dei dati nelle viste delle caratteristiche.

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

Quando non utilizzare gruppi di caratteristiche e caratteristiche

Se vuoi pubblicare gli incorporamenti dall'origine dati delle caratteristiche, non registrare l'origine dati creando gruppi di caratteristiche e caratteristiche. In questo scenario, devi configurare l'erogazione online associando direttamente la tabella BigQuery o la vista alle viste delle caratteristiche.

Per saperne di più sulla configurazione dell'erogazione online senza registrare l'origine dati delle caratteristiche, vedi Creare una vista delle caratteristiche da un'origine BigQuery.

Controllare l'accesso

Puoi controllare l'accesso a un gruppo di caratteristiche ai seguenti livelli:

  • Controllare l'accesso alla risorsa FeatureGroup: per controllare l'accesso a un gruppo di caratteristiche per una persona, un gruppo Google, un dominio o un account di servizio specifici, configura un criterio IAM per il gruppo di caratteristiche.

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

Prima di iniziare

Prima di creare un gruppo di caratteristiche, completa i seguenti prerequisiti:

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

  • 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.

  • Esegui l'autenticazione a Gemini Enterprise Agent Platform, se non l'hai già fatto.

    Seleziona la scheda relativa alla modalità di utilizzo degli esempi in questa pagina:

    Console

    Quando utilizzi la Google Cloud console per accedere a Google Cloud servizi e API, non devi configurare l'autenticazione.

    Python

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

    1. Installa Google Cloud CLI.

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

    3. Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente: 

      gcloud auth application-default login

      Non devi eseguire questa operazione se utilizzi Cloud Shell.

      Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

    REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi 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 Autenticati per usare REST nella Google Cloud documentazione sull'autenticazione di.

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 caratteristiche utilizzando la Google Cloud console:

  1. Nella sezione Piattaforma agente della Google Cloud console, vai alla Feature Store pagina.

    Vai alla pagina Feature Store

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

  3. Specifica il nome del gruppo di caratteristiche.

  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 caratteristiche.

  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 vista di origine BigQuery.

    Tieni presente che questa operazione è facoltativa se la tabella o la vista di origine BigQuery ha una colonna denominata entity_id. In questo caso, se non selezioni una colonna ID entità, il gruppo di caratteristiche 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 caratteristiche al nuovo gruppo di caratteristiche:

    • 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 caratteristiche: crea caratteristiche 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 caratteristiche, fai clic su Aggiungi un'altra caratteristica.

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

  9. Fai clic su Crea.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la Python documentazione di riferimento dell'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: il tuo ID progetto.
  • location: la regione in cui vuoi creare il gruppo di caratteristiche, ad esempio us-central1.
  • feature_group_id: il nome del nuovo gruppo di caratteristiche che vuoi creare.
  • bq_table_uri: l'URI della tabella o della vista di origine BigQuery che vuoi registrare per il gruppo di caratteristiche.
  • 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 FeatureGroup risorsa, invia una richiesta POST utilizzando il featureGroups.create metodo.

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

  • LOCATION_ID: la regione in cui vuoi creare il gruppo di caratteristiche, ad esempio us-central1.
  • SERVICE_AGENT_TYPE: (facoltativo) Configurazione del service account per il gruppo di caratteristiche. Per utilizzare un account di servizio dedicato per il gruppo di caratteristiche, 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 caratteristiche che vuoi creare.
  • BIGQUERY_SOURCE_URI: l'URI della tabella o della vista di origine BigQuery che vuoi registrare per il gruppo di caratteristiche.
  • TIMESTAMP_COLUMN: (facoltativo) Specifica il nome della colonna contenente i timestamp delle caratteristiche nella tabella o nella vista di origine BigQuery.
    Devi specificare il nome della colonna timestamp solo se i dati sono formattati come una serie temporale e la colonna contenente i timestamp delle caratteristiche non è denominata feature_timestamp.
  • STATIC_DATA_SOURCE: (facoltativo) Inserisci true se i dati non sono formattati come una 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 viste delle caratteristiche associate al gruppo di caratteristiche:
    • false: questa è l'impostazione predefinita. Vertex AI Feature Store pubblica solo i valori delle caratteristiche non null più recenti. Se l'ultimo valore di una caratteristica è null, Vertex AI Feature Store pubblica il valore storico non null più recente. Tuttavia, se i valori attuali e storici di questa caratteristica sono null, Vertex AI Feature Store pubblica null come valore della caratteristica.
    • true: per le viste delle caratteristiche con sincronizzazione dei dati pianificata, Vertex AI Feature Store pubblica solo i valori delle caratteristiche più recenti, inclusi i valori null. Per le viste delle caratteristiche con sincronizzazione continua dei dati, Vertex AI Feature Store pubblica solo i valori delle caratteristiche non null più recenti. Tuttavia, se i valori attuali e storici della caratteristica sono null, Vertex AI Feature Store pubblica null come valore della caratteristica. Per saperne di più sui tipi di sincronizzazione dei dati e su come configurare il tipo di sincronizzazione dei dati in una vista delle caratteristiche, vedi Sincronizzare i dati in una vista delle caratteristiche.

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, quindi esegui il comando seguente: 

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