监控功能

借助 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.

    5. 如需了解详情，请参阅 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。