Créer un groupe de caractéristiques

Un groupe de caractéristiques est une ressource du registre de caractéristiques associée à une table ou une vue BigQuery contenant vos données de caractéristiques. Un groupe de caractéristiques peut contenir plusieurs caractéristiques, chaque caractéristique étant associée à une colonne de la source de données de caractéristiques. Si vous souhaitez enregistrer votre source de données de caractéristiques dans le registre de caractéristiques, créez un groupe de caractéristiques, puis ajoutez-y des caractéristiques.

Après avoir créé un groupe de caractéristiques et associé la source de données BigQuery, vous pouvez créer des caractéristiques associées aux colonnes de la source de données. Notez que, bien qu'il soit facultatif d'associer une source de données lors de la création d'un groupe de caractéristiques, vous devez associer une table ou une vue BigQuery avant de créer des caractéristiques dans ce groupe. Chaque caractéristique correspond à une colonne de la source de données associée au groupe de caractéristiques.

Pourquoi utiliser des groupes de caractéristiques et des caractéristiques ?

L'enregistrement de votre source de données de caractéristiques est facultatif. Toutefois, vous devez enregistrer vos données de caractéristiques en créant des groupes de caractéristiques et des caractéristiques dans les cas suivants :

  • Utiliser des données historiques au format série temporelle pour entraîner un modèle : si la source de données de caractéristiques contient les données de caractéristiques les plus récentes ainsi que des données historiques avec plusieurs enregistrements de caractéristiques pour le même ID d'entité, mettez en forme ces données en tant que série temporelle en ajoutant la colonne feature_timestamp. Dans ce cas, vous devez enregistrer la source de données à l'aide de groupes de caractéristiques et de caractéristiques. Vous pouvez ensuite diffuser des caractéristiques comme suit :

    • Utilisez la diffusion en ligne pour diffuser les dernières valeurs de caractéristiques en fonction du code temporel afin d'effectuer des prédictions en temps réel.

    • Utilisez la diffusion hors connexion pour diffuser les valeurs de caractéristiques les plus récentes et historiques afin d'entraîner un modèle.

  • Agréger des caractéristiques provenant de plusieurs sources : utilisez des groupes de caractéristiques pour agréger des colonnes spécifiques provenant de plusieurs sources de données BigQuery lorsque vous créez une instance de vue de caractéristiques.

  • Diffuser des valeurs de caractéristiques nulles : lors de la diffusion en ligne, si vous souhaitez diffuser uniquement les dernières valeurs de caractéristiques, y compris les valeurs nulles, enregistrez votre source de données de caractéristiques en créant des groupes de caractéristiques avec le paramètre dense défini sur true.

  • Utiliser la synchronisation continue des données dans vos vues des caractéristiques : l'enregistrement de vos caractéristiques est une condition préalable à l'utilisation de la synchronisation continue des données dans vos vues des caractéristiques.

  • Surveiller les caractéristiques pour détecter les anomalies : vous devez enregistrer vos caractéristiques si vous souhaitez configurer la surveillance des caractéristiques pour récupérer les statistiques des caractéristiques et détecter les dérives.

Quand ne pas utiliser les groupes de caractéristiques et les caractéristiques

Si vous souhaitez diffuser des embeddings à partir de votre source de données de caractéristiques, n'enregistrez pas la source de données en créant des groupes de caractéristiques et des caractéristiques. Dans ce scénario, vous devez configurer la diffusion en ligne en associant directement la table ou la vue BigQuery à vos vues de caractéristiques.

Pour en savoir plus sur la configuration de la diffusion en ligne sans enregistrer votre source de données de caractéristiques, consultez Créer une vue de caractéristiques à partir d'une source BigQuery.

Contrôler les accès

Vous pouvez contrôler l'accès à un groupe de caractéristiques aux niveaux suivants :

  • Contrôler l'accès à la ressource FeatureGroup : pour contrôler l'accès à un groupe de caractéristiques pour une personne, un groupe Google, un domaine ou un compte de service spécifiques, configurez une stratégie IAM pour le groupe de caractéristiques.

  • Contrôler l'accès à la source de données BigQuery : par défaut, un groupe de caractéristiques utilise le compte de service par défaut configuré pour le projet. Vertex AI Feature Store attribue le rôle IAM (Identity and Access Management) Lecteur de données BigQuery à ce compte de service. Cela permet à tout utilisateur autorisé à créer un groupe de caractéristiques dans le projet d'accéder à la source de données de caractéristiques dans BigQuery. Pour limiter l'accès à la source de données BigQuery ou accorder l'accès à d'autres utilisateurs, vous pouvez configurer votre groupe de caractéristiques afin qu'il utilise son propre compte de service dédié. Vertex AI Feature Store génère une adresse e-mail de compte de service unique pour chaque groupe de caractéristiques configuré avec un compte de service dédié.

Avant de commencer

Avant de créer un groupe de caractéristiques, remplissez les conditions préalables suivantes :

  • Assurez-vous qu'au moins une instance de boutique en ligne est créée dans votre projet, même si vous souhaitez en créer une autre. Si vous utilisez un nouveau projet, créez une instance de boutique en ligne avant de créer le groupe de caractéristiques.

  • Mettez en forme vos données de caractéristiques dans la table ou la vue BigQuery pour qu'elles soient conformes aux Consignes de préparation des sources de données.

  • Vérifiez que votre source de données BigQuery contient au moins une colonne d'ID d'entité avec des valeurs string ou int.

  • Authentifiez-vous auprès de Vertex AI, sauf si vous l'avez déjà fait.

    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

    Pour utiliser les exemples Python de cette page dans un environnement de développement local, installez et initialisez la gcloud CLI, puis configurez le service Identifiants par défaut de l'application à l'aide de vos identifiants utilisateur.

      Installez la Google Cloud CLI.

      Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

      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.

    Pour en savoir plus, consultez la section Set up authentication for a local development environment.

    REST

    Pour utiliser les exemples API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à la gcloud CLI.

      Installez la Google Cloud CLI.

      Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

    Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud .

Créer un groupe de caractéristiques pour enregistrer une source de données de caractéristiques

Utilisez les exemples suivants pour créer un groupe de caractéristiques et associer une source de données de caractéristiques, telle qu'une table ou une vue BigQuery.

Console

Suivez les instructions ci-dessous pour créer un groupe de caractéristiques à l'aide de la console Google Cloud  :

  1. Dans la section Vertex AI de la console Google Cloud , accédez à la page Feature Store.

    Accéder à la page Feature Store

  2. Dans la section Groupes de caractéristiques, cliquez sur Créer pour ouvrir le volet Informations de base de la page Créer un groupe de caractéristiques.

  3. Spécifiez le nom du groupe de caractéristiques.

  4. Facultatif : Pour ajouter des étiquettes, cliquez sur Ajouter une étiquette, puis spécifiez son nom et sa valeur. Vous pouvez ajouter plusieurs étiquettes à un groupe de caractéristiques.

  5. Dans le champ Chemin d'accès dans BigQuery, cliquez sur Parcourir pour sélectionner la table ou la vue source BigQuery à associer au groupe de caractéristiques.

  6. Dans la liste Colonne "ID d'entité", sélectionnez les colonnes d'ID d'entité dans la table ou la vue source BigQuery.

    Notez que cette étape est facultative si la table ou la vue source BigQuery comporte une colonne nommée entity_id. Dans ce cas, si vous ne sélectionnez pas de colonne d'ID d'entité, le groupe de caractéristiques utilise la colonne entity_id comme colonne d'ID d'entité par défaut.

  7. Cliquez sur Continuer.

  8. Dans le volet Enregistrer, cliquez sur l'une des options suivantes pour indiquer si vous souhaitez ajouter des caractéristiques au nouveau groupe de caractéristiques :

    • Inclure toutes les colonnes de la table BigQuery : créez des caractéristiques dans le groupe de caractéristiques pour toutes les colonnes de la table ou de la vue source BigQuery.

    • Saisir manuellement vos caractéristiques : créez des caractéristiques en fonction de colonnes spécifiques de la source BigQuery. Spécifiez le nom de chaque caractéristique, puis cliquez sur le nom de la colonne source BigQuery correspondante dans la liste.

      Pour ajouter des caractéristiques, cliquez sur Ajouter une autre caractéristique.

    • Créer un groupe de caractéristiques vide : créez le groupe de caractéristiques sans y ajouter de caractéristiques.

  9. Cliquez sur Créer.

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'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 : ID de votre projet.
  • location : région dans laquelle vous souhaitez créer le groupe de caractéristiques, par exemple us-central1.
  • feature_group_id : nom du groupe de caractéristiques que vous souhaitez créer.
  • bq_table_uri : URI de la table ou de la vue source BigQuery que vous souhaitez enregistrer pour le groupe de caractéristiques.
  • entity_id_columns : noms des colonnes contenant les ID d'entité. Vous pouvez spécifier une ou plusieurs colonnes.
    • Pour ne spécifier qu'une seule colonne d'ID d'entité, spécifiez le nom de la colonne au format suivant :
      "entity_id_column_name".
    • Pour spécifier plusieurs colonnes d'ID d'entité, spécifiez les noms de colonne au format suivant :
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].

REST

Pour créer une ressource FeatureGroup, envoyez une requête POST à l'aide de la méthode featureGroups.create.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • LOCATION_ID : région dans laquelle vous souhaitez créer le groupe de caractéristiques, par exemple us-central1.
  • SERVICE_AGENT_TYPE : facultatif. Configuration du compte de service pour le groupe de caractéristiques. Pour utiliser un compte de service dédié pour le groupe de caractéristiques, saisissez SERVICE_AGENT_TYPE_FEATURE_GROUP.
  • PROJECT_ID : ID de votre projet
  • ENTITY_ID_COLUMNS : noms des colonnes contenant les ID d'entité. Vous pouvez spécifier une ou plusieurs colonnes.
    • Pour ne spécifier qu'une seule colonne d'ID d'entité, spécifiez le nom de la colonne au format suivant :
      "entity_id_column_name".
    • Pour spécifier plusieurs colonnes d'ID d'entité, spécifiez les noms de colonne au format suivant :
      ["entity_id_column_1_name", "entity_id_column_2_name", ...].
  • FEATUREGROUP_NAME : nom du groupe de caractéristiques que vous souhaitez créer.
  • BIGQUERY_SOURCE_URI : URI de la table ou de la vue source BigQuery que vous souhaitez enregistrer pour le groupe de caractéristiques.
  • TIMESTAMP_COLUMN : facultatif. Spécifiez le nom de la colonne contenant les codes temporels de caractéristiques dans la table ou la vue source BigQuery.
    Vous ne devez le faire que si les données sont mises en forme en tant que séries temporelles et que la colonne n'est pas nommée feature_timestamp.
  • STATIC_DATA_SOURCE : facultatif. Saisissez true si les données ne sont pas mises en forme en tant que séries temporelles. Le paramètre par défaut est false.
  • DENSE : facultatif. Indiquez comment Vertex AI Feature Store gère les valeurs nulles lors de la livraison de données à partir des vues de caractéristiques associées au groupe de caractéristiques :
    • false : paramètre par défaut. Vertex AI Feature Store ne livre que les dernières valeurs de caractéristiques non nulles. Si la dernière valeur d'une caractéristique est nulle, Vertex AI Feature Store livre la valeur historique non nulle la plus récente. Toutefois, si les valeurs actuelles et historiques de cette caractéristique sont nulles, Vertex AI Feature Store renvoie la valeur "null" comme valeur de la caractéristique.
    • true : pour les vues de caractéristiques avec synchronisation de données planifiée, Vertex AI Feature Store ne livre que les dernières valeurs de caractéristiques, y compris les valeurs nulles. Pour les vues de caractéristiques avec synchronisation continue des données, Vertex AI Feature Store ne livre que les dernières valeurs de caractéristiques non nulles. Toutefois, si les valeurs actuelles et historiques de la caractéristique sont nulles, Vertex AI Feature Store renvoie la valeur "null" comme valeur de la caractéristique. Pour en savoir plus sur les types de synchronisation des données et découvrir comment la configurer dans une vue de caractéristiques, consultez Synchroniser des données dans une vue de caractéristiques.

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Étapes suivantes