Fonctionnalités de surveillance

Vertex AI Feature Store vous permet de planifier et d'exécuter des tâches de surveillance des caractéristiques pour surveiller les données de caractéristiques, récupérer des statistiques sur les caractéristiques et détecter une dérive des caractéristiques. Vous ne pouvez surveiller les données de caractéristiques que si vous avez enregistré votre source de données de caractéristiques dans le registre de caractéristiques.

Pour surveiller les données d'éléments géographiques, vous pouvez créer la ressource FeatureMonitor sous une ressource FeatureGroup. Lorsque vous créez la ressource FeatureMonitor, vous pouvez configurer la planification de surveillance pour exécuter régulièrement des jobs de surveillance sur les données d'éléments géographiques. Vous pouvez également exécuter manuellement une tâche de surveillance des éléments géographiques pour surveiller vos données d'éléments géographiques en dehors de la planification de surveillance.

Pour chaque tâche de surveillance exécutée, Vertex AI Feature Store génère une ressource FeatureMonitorJob, que vous pouvez récupérer pour afficher les statistiques sur les caractéristiques et les informations sur la dérive détectée dans les données de caractéristiques.

Avant de commencer

Avant de surveiller des fonctionnalités à l'aide de Vertex AI Feature Store, remplissez les conditions préalables indiquées dans cette section.

Enregistrer une source de données d'éléments géographiques

Enregistrez votre source de données de caractéristiques à partir de BigQuery dans le registre de caractéristiques en créant des groupes de caractéristiques et des caractéristiques. Les ressources FeatureMonitor utilisées pour récupérer et surveiller les statistiques des éléments géographiques sont associées à des groupes d'éléments géographiques.

S'authentifier sur Vertex AI

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:

Python

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

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

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

REST

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

    Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

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

Créer un moniteur de fonctionnalité avec un calendrier de surveillance

Pour récupérer et surveiller les statistiques des éléments géographiques, créez une ressource FeatureMonitor spécifiant la planification d'exécution périodique des tâches de surveillance des éléments géographiques et récupérez les statistiques des éléments géographiques pour les éléments géographiques enregistrés dans le groupe d'éléments géographiques.

Utilisez les exemples suivants pour créer une ressource FeatureMonitor. Pour configurer plusieurs planifications pour le même groupe d'éléments géographiques, vous devez créer plusieurs ressources FeatureMonitor.

REST

Pour créer une ressource FeatureMonitor et planifier des tâches de surveillance des fonctionnalités, envoyez une requête POST à l'aide de la méthode featureMonitors.create.

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

  • LOCATION_ID: région dans laquelle vous souhaitez créer le moniteur de fonctionnalités, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe de caractéristiques dans lequel vous configurez la surveillance des caractéristiques.
  • FEATURE_MONITOR_NAME: nom du nouveau moniteur de fonctionnalités que vous souhaitez créer.
  • FEATURE_ID_1 et FEATURE_ID_2: ID des éléments que vous souhaitez surveiller.
  • DRIFT_THRESHOLD_1 et DRIFT_THRESHOLD_2: seuils de dérive pour chaque caractéristique incluse dans le moniteur de fonctionnalités. Le seuil de dérive permet de détecter les anomalies, telles que la dérive des caractéristiques. Saisissez une valeur comprise dans la plage [0, 1). Si vous ne saisissez aucune valeur, le seuil est défini par défaut sur 0.3.
    Vertex AI Feature Store compare les instantanés des exécutions de tâches de surveillance des caractéristiques consécutives et calcule les dérives à l'aide de la fonction ML.TFDV_VALIDATE dans BigQuery. Pour classer les anomalies, la distance L-infini est utilisée pour les caractéristiques catégorielles et la divergence Jensen-Shannon pour les caractéristiques numériques.
  • CRON: expression de programmation Cron représentant la fréquence d'exécution de la tâche de surveillance des fonctionnalités. Pour en savoir plus, consultez la section Cron.

Méthode HTTP et URL : 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors?feature_monitor_id=FEATURE_MONITOR_NAME

Corps JSON de la requête : 

{
  "feature_selection_config": {
    "feature_configs": [
      {"feature_id":"FEATURE_ID_1", "drift_threshold": "DRIFT_THRESHOLD_1" },
      {"feature_id":"FEATURE_ID_2", "drift_threshold": "DRIFT_THRESHOLD_2" }
    ],
  },
  "schedule_config": {
    "cron": "CRON"
  }
}

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/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors?feature_monitor_id=FEATURE_MONITOR_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/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors?feature_monitor_id=FEATURE_MONITOR_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/featureMonitors/FEATURE_MONITOR_NAME/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateFeatureMonitorOperationMetadata",
    "genericMetadata": {
      "createTime": "2024-12-15T19:35:03.975958Z",
      "updateTime": "2024-12-15T19:35:03.975958Z"
    }
  }
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

def create_feature_monitor_sample(
    project: str,
    location: str,
    existing_feature_group_id: str,
    feature_monitor_id: str,
    feature_selection_configs: List[Tuple[str, float]]
    schedule_config: str # Cron string. For example, "0 * * * *" indicates hourly execution.
):
    aiplatform.init(project="PROJECT_ID", location="LOCATION_ID")
    feature_group = feature_store.FeatureGroup("FEATUREGROUP_NAME")
    feature_monitor = feature_group.create_feature_monitor(
        name= "FEATURE_MONITOR_NAME",
        feature_selection_configs=[("FEATURE_ID_1", DRIFT_THRESHOLD_1),("FEATURE_ID_2", DRIFT_THRESHOLD_2)],
        schedule_config="CRON"
        )

Remplacez l'élément suivant :

  • LOCATION_ID: région dans laquelle vous souhaitez créer le moniteur de fonctionnalités, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe de caractéristiques dans lequel vous configurez la surveillance des caractéristiques.
  • FEATURE_MONITOR_NAME: nom du nouveau moniteur de fonctionnalités que vous souhaitez créer.
  • FEATURE_ID_1 et FEATURE_ID_2: ID des éléments que vous souhaitez surveiller.
  • DRIFT_THRESHOLD_1 et DRIFT_THRESHOLD_2: seuils de dérive pour chaque caractéristique incluse dans le moniteur de caractéristiques. Le seuil de dérive permet de détecter la dérive des caractéristiques. Saisissez une valeur comprise entre 0 et 1. Si vous ne saisissez aucune valeur, le seuil est défini par défaut sur 0.3.
    Vertex AI Feature Store compare l'instantané de données de la tâche de surveillance des caractéristiques actuelle à l'instantané de données de la tâche de surveillance des caractéristiques précédente. Notez que pour calculer l'écart de distribution, Vertex AI Feature Store utilise la fonction ML.TFDV_VALIDATE dans BigQuery.
    Pour la métrique utilisée pour comparer les statistiques, la distance L-infini est utilisée pour les caractéristiques catégorielles et la divergence Jensen-Shannon pour les caractéristiques numériques.
  • CRON: expression de programmation Cron représentant la fréquence d'exécution de la tâche de surveillance des fonctionnalités. Pour en savoir plus, consultez la section Cron.

Exécuter manuellement une tâche de surveillance des caractéristiques

Vous pouvez ignorer l'attente entre les tâches de surveillance des fonctionnalités planifiées consécutives et exécuter manuellement une tâche de surveillance des fonctionnalités. Cette fonctionnalité est utile si vous souhaitez récupérer des informations de surveillance et détecter immédiatement des anomalies dans les données de fonctionnalité au lieu d'attendre l'exécution du prochain job de surveillance planifié.

REST

Pour exécuter manuellement une tâche de surveillance des fonctionnalités en créant une ressource FeatureMonitorJob , envoyez une requête POST à l'aide de la méthode featureMonitorJobs.create.

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

  • LOCATION_ID: région dans laquelle vous souhaitez exécuter la tâche de surveillance des fonctionnalités, par exemple us-central1.
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • PROJECT_ID : ID de votre projet
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle vous souhaitez exécuter la tâche de surveillance des fonctionnalités.

Méthode HTTP et URL : 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_ID/featureMonitorJobs

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

curl

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 "" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_ID/featureMonitorJobs"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_ID/featureMonitorJobs" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID"
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

aiplatofrm.init(project="PROJECT_ID", location="LOCATION_ID")

feature_group = FeatureGroup.get("FEATUREGROUP_NAME}")
feature_monitor = feature_group.get_feature_monitor(FEATURE_MONITOR_NAME)
feature_monitor_job = feature_monitor.create_feature_monitor_job()

Remplacez l'élément suivant :

  • LOCATION_ID: région dans laquelle vous souhaitez exécuter la tâche de surveillance des fonctionnalités, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle vous souhaitez exécuter la tâche de surveillance des fonctionnalités.

Récupérer les statistiques des fonctionnalités à partir d'une tâche de surveillance

Vous pouvez récupérer les statistiques des éléments géographiques pour tous les éléments géographiques d'une tâche de surveillance des éléments géographiques en récupérant la ressource FeatureMonitorJob à l'aide de l'ID de tâche de surveillance des éléments géographiques généré lors de l'exécution de la tâche de surveillance des éléments géographiques. Vous pouvez également récupérer des statistiques sur les fonctionnalités pour une ressource spécifique pour le dernier travail de surveillance.

Répertorier les tâches de surveillance des éléments géographiques

Les exemples suivants montrent comment récupérer la liste de toutes les ressources FeatureMonitorJob créées pour une ressource FeatureMonitor donnée.

REST

Pour récupérer la liste des ressources FeatureMonitorJob pour une ressource FeatureMonitor spécifiée, envoyez une requête GET à l'aide de la méthode featureMonitorJobs.list.

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

  • LOCATION_ID: région où se trouve la ressource Feature, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle vous souhaitez lister les tâches de surveillance des fonctionnalités.

Méthode HTTP et URL : 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs

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

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs" | Select-Object -Expand Content

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

{
  "featureMonitorJobs": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID_1",
      "createTime": "2024-12-18T19:18:18.077161Z",
      "finalStatus": {},
      "featureSelectionConfig": {
        "featureConfigs": [
          {
            "featureId": "feature_name_1",
            "driftThreshold": 0.2
          },
          {
            "featureId": "feature_name_2",
            "driftThreshold": 0.2
          }
        ]
      }
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID_2",
      "createTime": "2024-12-19T19:18:30.859921Z",
      "finalStatus": {},
      "featureSelectionConfig": {
        "featureConfigs": [
          {
            "featureId": "feature_name_1",
            "driftThreshold": 0.2
          },
          {
            "featureId": "feature_name_2",
            "driftThreshold": 0.2
          }
        ]
      }
    }
  ]
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

aiplatofrm.init(project="PROJECT_ID", location="LOCATION_ID")

feature_group = FeatureGroup.get("FEATUREGROUP_NAME")
feature_monitor = feature_group.get_feature_monitor(FEATURE_MONITOR_NAME)
feature_monitor_jobs = feature_monitor.list_feature_monitor_jobs()

Remplacez l'élément suivant :

  • LOCATION_ID: région où se trouve la ressource Feature, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle vous souhaitez lister les tâches de surveillance des fonctionnalités.

Afficher les statistiques des éléments géographiques à partir d'une tâche de surveillance

Les exemples suivants montrent comment afficher les statistiques des éléments géographiques pour tous les éléments géographiques d'une tâche de surveillance des éléments géographiques. Pour chaque élément géographique, les statistiques et les anomalies sont affichées au format FeatureNameStatistics.

REST

Pour afficher les statistiques des éléments géographiques d'une tâche de surveillance en récupérant une ressource FeatureMonitorJob, envoyez une requête GET à l'aide de la méthode featureMonitorJobs.get.

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

  • LOCATION_ID: région dans laquelle la tâche de surveillance des fonctionnalités a été exécutée, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle la tâche de surveillance des fonctionnalités a été exécutée.
  • FEATURE_MONITOR_JOB_ID: ID de la ressource FeatureMonitorJob que vous souhaitez récupérer.

Méthode HTTP et URL : 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID

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

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID",
  "createTime": "2024-12-19T19:18:18.077161Z",
  "finalStatus": {},
  "jobSummary": {
    "featureStatsAndAnomalies": [
      {
        "featureId": "feature_id_1",
        "featureStats": {
          "name": "feature_name_1",
          "type": "STRING",
          "stringStats": {
            "commonStats": {
              "numNonMissing": "6",
              "minNumValues": "1",
              "maxNumValues": "1",
              "avgNumValues": 1,
              "numValuesHistogram": {
                "buckets": [
                  {
                    "lowValue": 1,
                    "highValue": 1,
                    "sampleCount": 0.6
                  },
                  {
                    "lowValue": 1,
                    "highValue": 1,
                    "sampleCount": 0.6
                  }
                ],
                "type": "QUANTILES"
              },
              "totNumValues": "6"
            },
            "unique": "2",
            "topValues": [
              {
                "value": "59",
                "frequency": 2
              },
              {
                "value": "19",
                "frequency": 1
              }
            ],
            "avgLength": 2,
            "rankHistogram": {
              "buckets": [
                {
                  "label": "59",
                  "sampleCount": 2
                },
                {
                  "lowRank": "1",
                  "highRank": "1",
                  "label": "19",
                  "sampleCount": 1
                }
              ]
            }
          }
        },
        "statsTime": "2024-12-19T19:18:18.077161Z",
        "featureMonitorJobId": "FEATURE_MONITOR_JOB_ID",
        "featureMonitorId": "FEATURE_MONITOR_NAME"
      },
      {
        "featureId": "feature_id_2",
        "featureStats": {
          "name": "feature_name_1",
          "type": "STRING",
          "stringStats": {
            "commonStats": {
              "numNonMissing": "6",
              "minNumValues": "1",
              "maxNumValues": "1",
              "avgNumValues": 1,
              "numValuesHistogram": {
                "buckets": [
                  {
                    "lowValue": 1,
                    "highValue": 1,
                    "sampleCount": 0.6
                  },
                  {
                    "lowValue": 1,
                    "highValue": 1,
                    "sampleCount": 0.6
                  }
                ],
                "type": "QUANTILES"
              },
              "totNumValues": "6"
            },
            "unique": "2",
            "topValues": [
              {
                "value": "59",
                "frequency": 2
              },
              {
                "value": "19",
                "frequency": 1
              }
            ],
            "avgLength": 2,
            "rankHistogram": {
              "buckets": [
                {
                  "label": "59",
                  "sampleCount": 2
                },
                {
                  "lowRank": "1",
                  "highRank": "1",
                  "label": "19",
                  "sampleCount": 1
                }
              ]
            }
          }
        },
        "statsTime": "2024-12-19T19:18:18.077161Z",
        "featureMonitorJobId": "FEATURE_MONITOR_JOB_ID",
        "featureMonitorId": "FEATURE_MONITOR_NAME"
      }
    ]
  },
  "driftBaseFeatureMonitorJobId": "2250003330000300000",
  "driftBaseSnapshotTime": "2024-12-12T16:00:01.211686Z",
  "featureSelectionConfig": {
    "featureConfigs": [
      {
        "featureId": "feature_id_1",
        "driftThreshold": 0.2
      },
      {
        "featureId": "feature_id_2",
        "driftThreshold": 0.2
      }
    ]
  },
  "triggerType": "FEATURE_MONITOR_JOB_TRIGGER_ON_DEMAND"
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

aiplatofrm.init(project="PROJECT_ID", location="LOCATION_ID")
feature_group = FeatureGroup.get("FEATUREGROUP_NAME"})

feature_monitor = feature_group.get_feature_monitor("FEATURE_MONITOR_NAME")
feature_monitor_job = feature_monitor.get_feature_monitor_job("FEATURE_MONITOR_JOB_ID)")

# Retrieve feature stats and anomalies
feature_stats_and_anomalies = feature_monitor_job.feature_stats_and_anomalies
print(feature_stats_and_anomalies)

Remplacez l'élément suivant :

  • LOCATION_ID: région dans laquelle la tâche de surveillance des fonctionnalités a été exécutée, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle la tâche de surveillance des fonctionnalités a été exécutée.
  • FEATURE_MONITOR_JOB_ID: ID de la ressource FeatureMonitorJob que vous souhaitez récupérer.

Afficher les statistiques des caractéristiques pour une caractéristique

Vous pouvez récupérer les statistiques des fonctionnalités pour une fonctionnalité spécifique à partir des tâches de surveillance des fonctionnalités les plus récentes exécutées en récupérant les détails de la fonctionnalité et en spécifiant le nombre de tâches de surveillance à partir desquelles vous souhaitez récupérer les statistiques. Les statistiques et les anomalies sont affichées au format FeatureNameStatistics.

Les exemples suivants montrent comment afficher les statistiques des fonctionnalités pour une fonctionnalité spécifique à partir d'un nombre spécifié de tâches de surveillance des fonctionnalités récentes.

REST

Pour afficher les statistiques des éléments géographiques pour un élément géographique spécifique dans une ressource Feature, envoyez une requête GET à l'aide de la méthode features.get et spécifiez le nombre de tâches de surveillance à partir desquelles récupérer les statistiques.

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

  • LOCATION_ID: région dans laquelle la tâche de surveillance des fonctionnalités a été exécutée, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME : nom du groupe de caractéristiques contenant la caractéristique.
  • FEATURE_NAME: nom de la ressource Feature pour laquelle vous souhaitez récupérer les statistiques sur les éléments géographiques.
  • LATEST_STATS_COUNT: numéro des dernières tâches de surveillance à partir desquelles les statistiques des fonctionnalités doivent être récupérées.

Méthode HTTP et URL : 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/features/FEATURE_NAME?feature_stats_and_anomaly_spec.latest_stats_count=LATEST_STATS_COUNT

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

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/features/FEATURE_NAME?feature_stats_and_anomaly_spec.latest_stats_count=LATEST_STATS_COUNT"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/features/FEATURE_NAME?feature_stats_and_anomaly_spec.latest_stats_count=LATEST_STATS_COUNT" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/features/FEATURE_NAME",
  "createTime": "2024-12-19T21:17:23.373559Z",
  "updateTime": "2024-12-19T21:17:23.373559Z",
  "etag": "sample_etag",
  "featureStatsAndAnomaly": [
    {
      "featureStats": {
        "name": "FEATURE_NAME",
        "type": "STRING",
        "stringStats": {
          "commonStats": {
            "numNonMissing": "4",
            "minNumValues": "1",
            "maxNumValues": "1",
            "avgNumValues": 1,
            "numValuesHistogram": {
              "buckets": [
                {
                  "lowValue": 1,
                  "highValue": 1,
                  "sampleCount": 0.4
                },
                {
                  "lowValue": 1,
                  "highValue": 1,
                  "sampleCount": 0.4
                },
                {
                  "lowValue": 1,
                  "highValue": 1,
                  "sampleCount": 0.4
                },
                {
                  "lowValue": 1,
                  "highValue": 1,
                  "sampleCount": 0.4
                }
              ],
              "type": "QUANTILES"
            },
            "totNumValues": "4"
          },
          "unique": "4",
          "topValues": [
            {
              "value": "feature_value_1",
              "frequency": 1
            },
            {
              "value": "feature_value_2",
              "frequency": 1
            },
            {
              "value": "feature_value_3",
              "frequency": 1
            },
            {
              "value": "feature_value_4",
              "frequency": 1
            }
          ],
          "avgLength": 4,
          "rankHistogram": {
            "buckets": [
              {
                "label": "label_1",
                "sampleCount": 1
              },
              {
                "lowRank": "1",
                "highRank": "1",
                "label": "label_2",
                "sampleCount": 1
              },
              {
                "lowRank": "2",
                "highRank": "2",
                "label": "label_3",
                "sampleCount": 1
              },
              {
                "lowRank": "3",
                "highRank": "3",
                "label": "label_4",
                "sampleCount": 1
              }
            ]
          }
        }
      },
      "driftDetectionThreshold": 0.1,
      "statsTime": "2024-12-19T22:00:02.734796Z",
      "featureMonitorJobId": "feature_monitor_job_id_1",
      "featureMonitorId": "feature_monitor_name_1"
    }
  ],
  "versionColumnName": "version_column_name"
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

aiplatofrm.init(project="PROJECT_ID", location="LOCATION_ID")

feature_group = FeatureGroup.get("FEATUREGROUP_NAME"})
feature_stats_and_anomalies = feature_group.get_feature("FEATURE_NAME", latest_stats_count=LATEST_STATS_COUNT)
print(feature_stats_and_anomalies)

Remplacez l'élément suivant :

  • LOCATION_ID: région dans laquelle la tâche de surveillance des fonctionnalités a été exécutée, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_NAME: nom de la caractéristique pour laquelle vous souhaitez récupérer les statistiques.
  • LATEST_STATS_COUNT: nombre de dernières tâches de surveillance à partir desquelles récupérer les statistiques des fonctionnalités.

Exemple de cas d'utilisation: utiliser la surveillance des fonctionnalités pour détecter les dérives

Vous pouvez utiliser la surveillance des fonctionnalités pour détecter une anomalie dans les données de fonctionnalités appelée dérive des fonctionnalités. Une dérive est un changement significatif et imprévu des données de caractéristiques dans BigQuery au fil du temps. Vertex AI Feature Store vous aide à identifier la dérive des caractéristiques en comparant l'instantané au moment de l'exécution de la tâche de surveillance à l'instantané des données lors de l'exécution de la tâche de surveillance précédente.

Pour toute caractéristique incluse dans le moniteur de caractéristiques, si la différence entre les deux instantanés dépasse le seuil spécifié dans le paramètre drift_threshold, Vertex AI Feature Store identifie une dérive de la caractéristique et renvoie les informations suivantes dans la ressource FeatureMonitorJob:

  • Le paramètre driftDetected est défini sur true.

  • Écart de distribution entre les deux instantanés. Pour les caractéristiques numériques, Vertex AI Feature Store calcule cette valeur à l'aide de la divergence Jensen-Shannon. Pour les caractéristiques de type catégorique, Vertex AI Feature Store calcule cette valeur à l'aide de la distance L-infini.

  • Seuil dépassé par l'écart de distribution.

Les exemples suivants montrent comment récupérer une ressource FeatureMonitorJob et vérifier si une dérive a été détectée.

REST

Pour récupérer une ressource FeatureMonitorJob , envoyez une requête GET à l'aide de la méthode featureMonitorJobs.get.

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

  • LOCATION_ID: région dans laquelle la tâche de surveillance des fonctionnalités a été exécutée, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle la tâche de surveillance des fonctionnalités a été exécutée.
  • FEATURE_MONITOR_JOB_ID: ID de la ressource FeatureMonitorJob que vous souhaitez récupérer.

Méthode HTTP et URL : 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID

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

curl

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID"

PowerShell

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/featureMonitors/FEATURE_MONITOR_NAME/featureMonitorJobs/FEATURE_MONITOR_JOB_ID",
  "createTime": "2024-12-14T19:45:30.026522Z",
  "finalStatus": {},
  "jobSummary": {
    "featureStatsAndAnomalies": [
      {
        "featureId": "feature_id_1",
        "featureStats": {
          "name": "feature_name_1",
          "type": "STRING",
          "stringStats": {
            "commonStats": {
              "numNonMissing": "3",
              "minNumValues": "1",
              "maxNumValues": "1",
              "avgNumValues": 1,
              "numValuesHistogram": {
                "buckets": [
                  {
                    "lowValue": 1,
                    "highValue": 1,
                    "sampleCount": 0.9
                  },
                  {
                    "lowValue": 1,
                    "highValue": 1,
                    "sampleCount": 0.9
                  },
                  {
                    "lowValue": 1,
                    "highValue": 1,
                    "sampleCount": 0.9
                  }
                ],
                "type": "QUANTILES"
              },
              "totNumValues": "3"
            },
            "unique": "3",
            "topValues": [
              {
                "value": "sample_value_1",
                "frequency": 1
              },
              {
                "value": "sample_value_2",
                "frequency": 1
              },
              {
                "value": "sample_value_3",
                "frequency": 1
              }
            ],
            "avgLength": 3,
            "rankHistogram": {
              "buckets": [
                {
                  "label": "sample_label_1",
                  "sampleCount": 1
                },
                {
                  "lowRank": "1",
                  "highRank": "1",
                  "label": "sample_label_2",
                  "sampleCount": 1
                },
                {
                  "lowRank": "2",
                  "highRank": "3",
                  "label": "sample_label_3",
                  "sampleCount": 1
                }
              ]
            }
          }
        },
        "distributionDeviation": 0.1388880008888000,
        "driftDetectionThreshold": 0.1,
        "driftDetected": true,
        "statsTime": "2024-12-15T19:45:37.026522Z",
        "featureMonitorJobId": "FEATURE_MONITOR_JOB_ID",
        "featureMonitorId": "FEATURE_MONITOR_NAME"
      }
    ]
  },
  "driftBaseFeatureMonitorJobId": "2250003330000300000",
  "driftBaseSnapshotTime": "2024-12-12T18:18:18.077161Z",
  "description": "sample_feature_monitor_job_description",
  "featureSelectionConfig": {
    "featureConfigs": [
      {
        "featureId": "feature_name",
        "driftThreshold": 0.1
      }
    ]
  },
  "triggerType": "FEATURE_MONITOR_JOB_TRIGGER_ON_DEMAND"
}

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local. 

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

aiplatofrm.init(project="PROJECT_ID", location="LOCATION_ID")
feature_group = FeatureGroup.get("FEATUREGROUP_NAME"})
feature_monitor = feature_group.get_feature_monitor("FEATURE_MONITOR_NAME")
feature_monitor_job = feature_monitor.get_feature_monitor_job("FEATURE_MONITOR_JOB_ID)")

# Retrieve feature stats and anomalies
feature_stats_and_anomalies = feature_monitor_job.feature_stats_and_anomalies
print(feature_stats_and_anomalies)

# Check whether drifts are detected
for feature_stats_and_anomalies in feature_monitor_job.feature_stats_and_anomalies:
    print("feature: ", feature_stats_and_anomalies.feature_id)
    print("distribution deviation: ", feature_stats_and_anomalies.distribution_deviation)
    print("drift detected: ", feature_stats_and_anomalies.drift_detected)

Remplacez l'élément suivant :

  • LOCATION_ID: région dans laquelle la tâche de surveillance des fonctionnalités a été exécutée, par exemple us-central1.
  • PROJECT_ID : ID de votre projet
  • FEATUREGROUP_NAME: nom du groupe d'éléments géographiques contenant la ressource FeatureMonitor.
  • FEATURE_MONITOR_NAME: nom de la ressource FeatureMonitor pour laquelle la tâche de surveillance des fonctionnalités a été exécutée.
  • FEATURE_MONITOR_JOB_ID: ID de la ressource FeatureMonitorJob que vous souhaitez récupérer.