建立特徵群組

特徵群組是與包含特徵資料的 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 資料來源至少包含一個實體 ID 欄，且該欄含有 string 或 int 值。

• 向 Vertex AI 進行驗證 (如果尚未完成)。

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

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  Python

  如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

  安裝 Google Cloud CLI。

  如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  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。

  REST

  如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

  安裝 Google Cloud CLI。

  如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。

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

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

控制台

重要事項： 您無法使用 Google Cloud 控制台的專屬服務帳戶建立功能群組。如要使用專屬服務帳戶建立特徵群組，請使用 REST API 或 Python 適用的 Vertex AI SDK。

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

1. 在 Google Cloud 控制台的 Vertex AI 專區中，前往「Feature Store」頁面。

   前往 Feature Store 頁面

2. 在「功能群組」部分中，按一下「建立」，開啟「建立功能群組」頁面上的「基本資訊」窗格。

3. 指定「特徵群組名稱」。

4. 選用：如要新增標籤，請按一下「新增標籤」，然後指定標籤名稱和值。您可以為特徵群組新增多個標籤。

5. 在「BigQuery 路徑」欄位中，按一下「瀏覽」，選取要與特徵群組建立關聯的 BigQuery 來源資料表或檢視表。

6. 在「實體 ID 資料欄」清單中，從 BigQuery 來源資料表或檢視區塊選取實體 ID 資料欄。

   請注意，如果 BigQuery 來源資料表或檢視表有名為 entity_id 的資料欄，則此為選用步驟。在這種情況下，如果未選取實體 ID 資料欄，特徵群組會使用 entity_id 資料欄做為預設實體 ID 資料欄。

7. 按一下「繼續」。

8. 在「Register」(註冊) 窗格中，按一下下列任一選項，指出是否要將功能新增至新的功能群組：

   • 加入 BigQuery 資料表中的所有資料欄：為 BigQuery 來源資料表或檢視表中的所有資料欄，在特徵群組中建立特徵。

   • 手動輸入特徵：根據 BigQuery 來源中的特定資料欄建立特徵。為每個特徵輸入「特徵名稱」，然後在清單中按一下對應的 BigQuery 來源資料欄名稱。

     如要新增更多功能，請按一下「新增其他功能」。

   • 建立空的特徵群組：建立特徵群組，但不新增特徵。

9. 點選「建立」。

Python

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK，請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 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"
    }
  }
}

後續步驟

• 瞭解如何建立功能。

• 瞭解如何更新特徵群組。

• 瞭解如何刪除功能群組。