建立特徵群組

特徵群組是與 BigQuery 資料表或檢視區塊相關聯的特徵註冊庫資源，內含特徵資料。特徵群組可以包含多個特徵，每個特徵都與特徵資料來源中的資料欄相關聯。如要在特徵登錄中註冊特徵資料來源，請建立特徵群組，然後新增特徵。

建立特徵群組並關聯 BigQuery 資料來源後，即可建立特徵，並與資料來源中的資料欄建立關聯。請注意，雖然建立特徵群組時可以選擇是否要關聯資料來源，但您必須先關聯 BigQuery 資料表或檢視區塊，才能在該特徵群組中建立特徵。每個特徵都會對應至與特徵群組相關聯的資料來源中的資料欄。

為什麼要使用特徵群組和特徵？

您可以選擇是否註冊特徵資料來源。不過，在下列情況中，您必須建立特徵群組和特徵，藉此註冊特徵資料：

使用時間序列格式的歷來資料訓練模型：如果特徵資料來源包含最新和歷來特徵資料，且同一實體 ID 有多筆特徵記錄，請新增 feature_timestamp 欄，將這類資料格式化為時間序列。在這個情境中，您必須使用特徵群組和特徵註冊資料來源。接著，您可以按照下列步驟提供特徵：
- 使用線上提供服務，根據時間戳記提供最新的特徵值，以進行即時預測。
- 使用離線供應服務，提供最新和過往的特徵值來訓練模型。
匯總多個來源的特徵：建立特徵檢視區塊執行個體時，使用特徵群組匯總多個 BigQuery 資料來源的特定資料欄。
提供空值特徵值：在線上供應期間，如果只想提供最新特徵值 (包括空值)，請建立特徵群組並將 dense 參數設為 true，藉此註冊特徵資料來源。

注意： 如要提供空值特徵值，您也必須使用為 Bigtable 線上提供功能設定的線上商店執行個體，並在特徵檢視區塊中使用排定的資料同步。
在特徵檢視畫面中使用持續資料同步功能：如要在特徵檢視畫面中使用持續資料同步功能，必須先註冊特徵。
注意：
如要使用連續資料同步功能，還必須符合下列條件：
- 網路商店執行個體必須設定為 Bigtable 線上提供。
- 相關聯的 BigQuery 資料來源必須位於 eu、us 或 us-central1。
監控特徵是否有異常情形：如要設定特徵監控，以便擷取特徵統計資料及偵測特徵偏移情形，就必須註冊特徵。

不適合使用特徵群組和特徵的情況

如要提供嵌入內容，請勿建立特徵群組和特徵，藉此註冊資料來源。在這種情況下，您必須直接將 BigQuery 資料表或檢視區塊與特徵檢視區塊建立關聯，藉此設定線上提供。

如要進一步瞭解如何在不註冊特徵資料來源的情況下設定線上提供，請參閱「從 BigQuery 來源建立特徵檢視區塊」。

控管存取權

您可以在下列層級控管功能群組的存取權：

控管 FeatureGroup 資源的存取權：如要控管特定個人、Google 群組、網域或服務帳戶的功能群組存取權，請為功能群組設定 IAM 政策。
控管 BigQuery 資料來源的存取權：根據預設，特徵群組會使用為專案設定的預設服務帳戶。Vertex AI 特徵儲存庫會將 BigQuery 資料檢視者身分與存取權管理 (IAM) 角色指派給這個服務帳戶。這樣一來，專案中具備建立特徵群組權限的使用者，就能存取 BigQuery 中的特徵資料來源。如要限制 BigQuery 資料來源的存取權，或授予其他使用者存取權，您可以設定特徵群組，使用專屬的服務帳戶。針對設定專屬服務帳戶的每個特徵群組，Vertex AI 特徵儲存庫會產生專屬的服務帳戶電子郵件地址。
注意：
如要查看功能群組的專屬服務帳戶電子郵件地址，請採取下列其中一種做法：
- 使用 featureGroups.list 方法擷取所有功能群組的清單。
- 使用 featureGroups.get 方法擷取特徵群組的詳細資料。

事前準備

建立特徵群組前，請先完成下列必要條件：

請確認專案中至少已建立一個網路商店執行個體，即使您想建立新的網路商店執行個體也一樣。如果您使用新專案，請先建立網路商店執行個體，再建立特徵群組。
在 BigQuery 資料表或檢視表中設定特徵資料格式，使其符合資料來源準備指南。
確認 BigQuery 資料來源至少包含一個含有 string 或 int 值的實體 ID 欄。
驗證 Gemini Enterprise Agent Platform，除非您已完成驗證。
選取這個頁面上範例的預計用途分頁：
控制台

使用 Cloud de Confiance 控制台存取 Cloud de Confiance by S3NS 服務和 API 時，不需要設定驗證。
Python

如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。
1. 安裝 Google Cloud CLI。
2. 設定 gcloud CLI，使用您的聯合身分。
  
  詳情請參閱「使用聯合身分登入 gcloud CLI」。
3. 為使用者帳戶建立本機驗證憑證：
  gcloud auth application-default login
  如果系統傳回驗證錯誤，請確認您已使用聯合身分登入 gcloud CLI。
詳情請參閱「設定本機開發環境的驗證機制」。
REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。
詳情請參閱 Cloud de Confiance 驗證說明文件中的「使用 REST 進行驗證」。

建立特徵群組，註冊特徵資料來源

使用下列範例建立特徵群組，並關聯特徵資料來源，例如 BigQuery 資料表或檢視區塊。

控制台

重要事項：您無法透過 Cloud de Confiance 控制台，使用專屬服務帳戶建立特徵群組。如要使用專屬服務帳戶建立特徵群組，請使用 REST API 或 Agent Platform Python SDK。

請按照下列操作說明，使用 Cloud de Confiance 控制台建立特徵群組：

在 Cloud de Confiance 控制台的「Agent Platform」部分，前往「特徵儲存庫」頁面。

前往「特徵儲存庫」頁面
在「特徵群組」部分中，按一下「建立」，開啟「建立特徵群組」頁面的「基本資訊」窗格。
指定「特徵群組名稱」。
選用：如要新增標籤，請按一下「新增標籤」，然後指定標籤名稱和值。您可以為特徵群組新增多個標籤。
在「BigQuery 路徑」欄位中，按一下「瀏覽」，選取要與特徵群組建立關聯的 BigQuery 來源資料表或檢視區塊。
在「實體 ID 資料欄」清單中，從 BigQuery 來源資料表或檢視畫面選取實體 ID 資料欄。

請注意，如果 BigQuery 來源資料表或檢視區塊有名為 entity_id 的資料欄，則這是選用步驟。在這種情況下，如果未選取實體 ID 欄，特徵群組會使用 entity_id 欄做為預設實體 ID 欄。
按一下「繼續」。
在「Register」(註冊) 窗格中，按一下下列任一選項，指出是否要將功能新增至新功能群組：
- 加入 BigQuery 資料表中的所有資料欄：為 BigQuery 來源資料表或檢視表中的所有資料欄，在特徵群組中建立特徵。
- 手動輸入特徵：根據 BigQuery 來源中的特定資料欄建立特徵。為每個特徵輸入「特徵名稱」，然後在清單中點選對應的 BigQuery 來源資料欄名稱。
  
  如要新增更多特徵，請按一下「新增其他特徵」。
- 建立空的特徵群組：建立特徵群組，但不新增特徵。
點選「建立」。

Python

如要瞭解如何安裝或更新 Vertex AI SDK for Python，請參閱「安裝 Vertex AI SDK for Python」。詳情請參閱 Python API 參考文件。

注意：這個範例會使用預設服務帳戶設定建立特徵群組。


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


def create_feature_group_sample(
    project: str,
    location: str,
    feature_group_id: str,
    bq_table_uri: str,
    entity_id_columns: List[str],
):
    aiplatform.init(project=project, location=location)
    fg = feature_store.FeatureGroup.create(
        name=feature_group_id,
        source=feature_store.utils.FeatureGroupBigQuerySource(
            uri=bq_table_uri, entity_id_columns=entity_id_columns
        ),
    )
    return fg

project：專案 ID。
location：要建立特徵群組的區域，例如 us-central1。
feature_group_id：要建立的新特徵群組名稱。
bq_table_uri：要為特徵群組註冊的 BigQuery 來源資料表或檢視區塊 URI。
entity_id_columns：包含實體 ID 的資料欄名稱。您可以指定一或多個欄。
- 如要只指定一個實體 ID 欄，請使用下列格式指定欄名：
  "entity_id_column_name"。
- 如要指定多個實體 ID 欄，請採用下列格式指定欄名：
  ["entity_id_column_1_name", "entity_id_column_2_name", ...]。

REST

如要建立 FeatureGroup 資源，請使用 featureGroups.create 方法傳送 POST 要求。

使用任何要求資料之前，請先修改下列項目的值：

LOCATION_ID：要建立特徵群組的區域，例如 us-central1。
SERVICE_AGENT_TYPE：選用。特徵群組的服務帳戶設定。如要為功能群組使用專屬服務帳戶，請輸入 SERVICE_AGENT_TYPE_FEATURE_GROUP。
PROJECT_ID：專案 ID。
ENTITY_ID_COLUMNS：包含實體 ID 的資料欄名稱。您可以指定一或多個欄。
- 如要只指定一個實體 ID 欄，請使用下列格式指定欄名：
  "entity_id_column_name"。
- 如要指定多個實體 ID 欄，請採用下列格式指定欄名：
  ["entity_id_column_1_name", "entity_id_column_2_name", ...]。
FEATUREGROUP_NAME：要建立的新特徵群組名稱。
BIGQUERY_SOURCE_URI：要為特徵群組註冊的 BigQuery 來源資料表或檢視區塊 URI。
TIMESTAMP_COLUMN：選用。在 BigQuery 來源資料表或檢視表中，指定包含特徵時間戳記的資料欄名稱。
只有在資料格式為時間序列，且包含特徵時間戳記的資料欄並未命名為 feature_timestamp 時，才需要指定時間戳記資料欄名稱。

注意：如果將 static_data_source 參數設為 true，請勿加入 time_series 參數。
STATIC_DATA_SOURCE：選用。如果資料未採用時間序列格式，請輸入 true。預設為 false。

注意：如果使用 time_series 參數，請勿加入 static_data_source 參數。
DENSE：選用。指出 Vertex AI 特徵儲存庫在從與特徵群組相關聯的特徵檢視畫面提供資料時，如何處理空值：
- false：這是預設設定。Vertex AI 特徵儲存庫只會提供最新的非空值特徵值。如果特徵的最新值為空值，Vertex AI 特徵儲存庫會提供最近的非空值歷史記錄值。不過，如果該特徵的目前值和歷史值皆為空值，Vertex AI 特徵儲存庫就會將空值做為特徵值。
- true—對於排定資料同步的特徵檢視畫面，Vertex AI 特徵儲存庫只會提供最新的特徵值，包括空值。如果特徵檢視區塊持續同步資料，Vertex AI 特徵儲存庫只會提供最新的非空值特徵值。不過，如果特徵的目前值和歷史值皆為空值，Vertex AI 特徵儲存庫會將空值做為特徵值。如要進一步瞭解資料同步類型，以及如何在特徵檢視畫面中設定資料同步類型，請參閱「同步特徵檢視畫面中的資料」。

HTTP 方法和網址：

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

JSON 要求內文：

{
  "service_agent_type": "SERVICE_AGENT_TYPE",
  "big_query": {
    "entity_id_columns": "ENTITY_ID_COLUMNS",
    "big_query_source": {
      "input_uri": "BIGQUERY_SOURCE_URI",
    }
    "time_series": {
      "timestamp_column": ""TIMESTAMP_COLUMN"",
    },
    "static_data_source": STATIC_DATA_SOURCE,
    "dense": DENSE
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureGroups?feature_group_id=FEATUREGROUP_NAME" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureGroups/FEATUREGROUP_NAME/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateFeatureGroupOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-09-18T03:00:13.060636Z",
      "updateTime": "2023-09-18T03:00:13.060636Z"
    }
  }
}

後續步驟

瞭解如何建立功能。
瞭解如何更新特徵群組。
瞭解如何刪除功能群組。