监控功能

借助 Vertex AI Feature Store，您可以安排和运行特征监控作业，以监控特征数据、检索特征统计信息和检测特征偏移。只有在特征注册表中注册了特征数据源后，您才能监控特征数据。

如需监控特征数据，您可以在 FeatureGroup 资源下创建 FeatureMonitor 资源。创建 FeatureMonitor 资源时，您可以配置监控时间表，以定期对特征数据运行监控作业。或者，您也可以手动运行特征监控作业，以便在监控计划之外监控特征数据。

对于执行的每个监控作业，Vertex AI Feature Store 都会生成一个 FeatureMonitorJob 资源，您可以检索该资源以查看特征统计信息以及在特征数据中检测到的漂移相关信息。

准备工作

在使用 Vertex AI Feature Store 监控特征之前，请先完成本部分中列出的前提条件。

注册功能数据源

通过创建特征组和特征，在特征注册表中注册来自 BigQuery 的特征数据源。用于检索和监控特征统计信息的 FeatureMonitor 资源与特征组相关联。

向 Vertex AI 进行身份验证

向 Vertex AI 进行身份验证，除非您已完成此操作。

Select the tab for how you plan to use the samples on this page:

Python

如需在本地开发环境中使用本页面上的 Python 示例，请安装并初始化 gcloud CLI，然后使用您的用户凭据设置应用默认凭据。

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

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

如需了解详情，请参阅 Set up authentication for a local development environment。 如需了解详情，请参阅身份验证文档中的为本地开发环境设置 ADC。

REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

    After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

创建具有监控时间表的特征监控

如需检索和监控特征统计信息，请创建 FeatureMonitor 资源，指定定期执行特征监控作业的时间表，并检索特征组中注册的特征的特征统计信息。

使用以下示例创建 FeatureMonitor 资源。如需为同一特征组设置多个时间表，您必须创建多个 FeatureMonitor 资源。

REST

如需创建 FeatureMonitor 资源并安排特征监控作业，请使用 featureMonitors.create 方法发送 POST 请求。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：要在其中创建特征监控器的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：设置了特征监控的特征组的名称。
  • FEATURE_MONITOR_NAME：您要创建的新功能监控器的名称。
  • FEATURE_ID_1 和 FEATURE_ID_2：要监控的特征的 ID。
  • DRIFT_THRESHOLD_1 和 DRIFT_THRESHOLD_2：特征监控器中包含的每个特征的漂移阈值。漂移阈值用于检测异常情况，例如特征漂移。输入一个介于 [0, 1) 之间的值。如果您未输入值，则默认情况下阈值设置为 0.3。
    Vertex AI Feature Store 会比较连续的特征监控作业执行中的快照，并使用 BigQuery 中的 ML.TFDV_VALIDATE 函数计算漂移。 为了对异常情况进行分类，系统会针对分类特征使用 L-无穷大距离，针对数值特征使用 Jensen-Shannon 差异。
  • CRON：Cron 时间表表达式，表示运行特征监控作业的频率。如需了解详情，请参阅 cron。

HTTP 方法和网址：

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

请求 JSON 正文： 

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

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

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

将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

$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

您应该收到类似以下内容的 JSON 响应：

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

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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"
        )

请替换以下内容：

  • LOCATION_ID：要在其中创建特征监控器的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：设置了特征监控的特征组的名称。
  • FEATURE_MONITOR_NAME：您要创建的新功能监控器的名称。
  • FEATURE_ID_1 和 FEATURE_ID_2：要监控的特征的 ID。
  • DRIFT_THRESHOLD_1 和 DRIFT_THRESHOLD_2：特征监控器中包含的每个特征的漂移阈值。漂移阈值用于检测特征漂移。请输入介于 0 和 1 之间的值。如果您未输入值，则系统默认将阈值设置为 0.3。
    Vertex AI Feature Store 会将当前特征监控作业中的数据快照与上一个特征监控作业中的数据快照进行比较。 请注意，为了计算分布偏差，Vertex AI Feature Store 使用 BigQuery 中的 ML.TFDV_VALIDATE 函数。
    对于用于比较统计信息的指标，分类特征使用 L-无穷大距离， 数值特征使用 Jensen-Shannon 差异。
  • CRON：Cron 时间表表达式，表示运行特征监控作业的频率。如需了解详情，请参阅 cron。

手动运行特征监控作业

您可以跳过连续安排的特征监控作业之间的等待时间，并手动运行特征监控作业。如果您想立即检索监控信息并检测特征数据中的异常情况，而不是等待下一个预定的监控作业运行，那么此方法非常有用。

REST

如需通过创建 FeatureMonitorJob 资源来手动运行特征监控作业，请使用 featureMonitorJobs.create 方法发送 POST 请求。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：您要运行特征监控作业的区域，例如 us-central1。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • PROJECT_ID：您的项目 ID。
  • FEATURE_MONITOR_NAME：您要为其运行特征监控作业的 FeatureMonitor 资源的名称。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

Python

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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()

请替换以下内容：

  • LOCATION_ID：您要运行特征监控作业的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_MONITOR_NAME：您要为其运行特征监控作业的 FeatureMonitor 资源的名称。

从监控作业中检索特征统计信息

您可以使用在特征监控作业执行期间生成的特征监控作业 ID 来检索 FeatureMonitorJob 资源，从而检索特征监控作业中所有特征的特征统计信息。您还可以检索最新监控作业中特定资源的功能统计信息。

列出特征监控作业

以下示例展示了如何检索为给定 FeatureMonitor 资源创建的所有 FeatureMonitorJob 资源的列表。

REST

如需检索指定 FeatureMonitor 资源的 FeatureMonitorJob 资源列表，请使用 featureMonitorJobs.list 方法发送 GET 请求。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：Feature 资源所在的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_MONITOR_NAME：您要为其列出特征监控作业的 FeatureMonitor 资源的名称。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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()

请替换以下内容：

  • LOCATION_ID：Feature 资源所在的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_MONITOR_NAME：您要为其列出特征监控作业的 FeatureMonitor 资源的名称。

查看监控作业中的特征统计信息

以下示例展示了如何查看特征监控作业中所有特征的特征统计信息。对于每个功能，统计信息和异常情况都以 FeatureNameStatistics 格式显示。

REST

如需通过检索 FeatureMonitorJob 资源来查看监控作业中的特征统计信息，请使用 featureMonitorJobs.get 方法发送 GET 请求。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：运行特征监控作业的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_MONITOR_NAME：运行特征监控作业所针对的 FeatureMonitor 资源的名称。
  • FEATURE_MONITOR_JOB_ID：要检索的 FeatureMonitorJob 资源的 ID。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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)

请替换以下内容：

  • LOCATION_ID：运行特征监控作业的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_MONITOR_NAME：运行特征监控作业所针对的 FeatureMonitor 资源的名称。
  • FEATURE_MONITOR_JOB_ID：您要检索的 FeatureMonitorJob 资源的 ID。

查看特征的特征统计信息

您可以检索最近执行的特征监控作业中特定特征的特征统计信息，方法是检索特征详情并指定要从中检索统计信息的监控作业数量。统计信息和异常情况以 FeatureNameStatistics 格式显示。

以下示例展示了如何查看指定数量的近期特征监控作业中特定特征的特征统计信息。

REST

如需查看 Feature 资源中特定特征的特征统计信息，请使用 features.get 方法发送 GET 请求，并指定要从中检索统计信息的监控作业数量。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：运行特征监控作业的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含特征的特征组的名称。
  • FEATURE_NAME：您要检索特征统计信息的 Feature 资源的名称。
  • LATEST_STATS_COUNT：要从中检索特征统计信息的最新监控作业的数量。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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)

请替换以下内容：

  • LOCATION_ID：运行特征监控作业的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_NAME：要检索特征统计信息的特征的名称。
  • LATEST_STATS_COUNT：要从中检索特征统计信息的最新监控作业的数量。

使用场景示例：使用特征监控来检测特征偏移

您可以使用特征监控来检测特征数据中的异常情况，即特征漂移。漂移是指 BigQuery 中的特征数据随时间推移而发生的显著且无法预料的变化。Vertex AI Feature Store 可通过比较监控作业运行时的快照与上一次监控作业执行期间的数据快照，帮助您识别特征偏移。

对于特征监控器中包含的任何特征，如果两个快照之间的差异超过 drift_threshold 参数中指定的阈值，Vertex AI Feature Store 会识别出特征漂移，并在 FeatureMonitorJob 资源中返回以下信息：

  • driftDetected 参数设置为 true。

  • 两个快照之间的分布偏差。 对于数值特征，Vertex AI Feature Store 使用 Jensen-Shannon 差异计算此值。对于分类特征，Vertex AI Feature Store 使用 L-无穷大距离计算此值。

  • 分布偏差超过的阈值。

以下示例展示了如何检索 FeatureMonitorJob 资源并验证是否检测到漂移。

REST

如需检索 FeatureMonitorJob 资源，请使用 featureMonitorJobs.get 方法发送 GET 请求。

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION_ID：运行特征监控作业的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_MONITOR_NAME：运行特征监控作业所针对的 FeatureMonitor 资源的名称。
  • FEATURE_MONITOR_JOB_ID：您要检索的 FeatureMonitorJob 资源的 ID。

HTTP 方法和网址：

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

如需发送请求，请选择以下方式之一：

curl

执行以下命令：

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

执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 Vertex AI Python API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

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)

请替换以下内容：

  • LOCATION_ID：运行特征监控作业的区域，例如 us-central1。
  • PROJECT_ID：您的项目 ID。
  • FEATUREGROUP_NAME：包含 FeatureMonitor 资源的特征组的名称。
  • FEATURE_MONITOR_NAME：运行特征监控作业所针对的 FeatureMonitor 资源的名称。
  • FEATURE_MONITOR_JOB_ID：您要检索的 FeatureMonitorJob 资源的 ID。