線上提供

線上供應服務可讓您以低延遲方式,為小批實體提供特徵值。每個要求只能提供單一實體類型的特徵值。Vertex AI 特徵儲存庫 (舊版) 只會傳回每個特徵的最新非空值

一般來說,您會使用線上服務,將特徵值提供給已部署的模型,以進行線上推論。舉例來說,假設您經營自行車共享公司,並想預測特定使用者租借自行車的時間長度。您可以納入使用者的即時輸入內容和特徵商店的資料,執行線上推論。這樣一來,您就能即時決定資源分配。

空值

如果是線上提供結果,如果特徵的最新值為空值,Vertex AI 特徵儲存庫 (舊版) 會傳回最新的非空值。如果沒有先前的值,Vertex AI 特徵儲存庫 (舊版) 會傳回空值。

事前準備

確認您要呼叫的 Feature Store 具有線上商店 (節點數量必須大於 0)。否則,線上服務要求會傳回錯誤。詳情請參閱「管理特徵存放區」。

從單一實體提供值

針對特定實體類型,從單一實體提供特徵值。

REST

如要從實體取得特徵值,請使用 featurestores.entityTypes.readFeatureValues 方法傳送 POST 要求。

以下範例會取得特定實體的兩項不同特徵的最新值。請注意,針對 ids 欄位,您可以指定 ["*"],而非特徵 ID,藉此選取實體的所有特徵。

使用任何要求資料之前,請先替換以下項目:

  • LOCATION_ID:建立特徵商店的區域。例如:us-central1
  • PROJECT_ID:您的專案 ID
  • FEATURESTORE_ID:特徵商店的 ID。
  • ENTITY_TYPE_ID:實體類型 ID。
  • ENTITY_ID:要取得特徵值的實體 ID。
  • FEATURE_ID:要取得值的特徵 ID。

HTTP 方法和網址:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:readFeatureValues

JSON 要求主體:

{
  "entityId": "ENTITY_ID",
  "featureSelector": {
    "idMatcher": {
      "ids": ["FEATURE_ID_1", "FEATURE_ID_2"]
    }
  }
}

如要傳送要求,請選擇以下其中一個選項:

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/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:readFeatureValues"

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/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:readFeatureValues" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應:

{
  "header": {
    "entityType": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID",
    "featureDescriptors": [
      {
        "id": "FEATURE_ID_1"
      },
      {
        "id": "FEATURE_ID_2"
      }
    ]
  },
  "entityView": {
    "entityId": "ENTITY_ID",
    "data": [
      {
        "value": {
          "VALUE_TYPE_1": "FEATURE_VALUE_1",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      },
      {
        "value": {
          "VALUE_TYPE_2": "FEATURE_VALUE_2",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      }
    ]
  }
}

Python

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Python API 參考說明文件

from typing import List, Union

from google.cloud import aiplatform


def read_feature_values_sample(
    project: str,
    location: str,
    entity_type_id: str,
    featurestore_id: str,
    entity_ids: Union[str, List[str]],
    feature_ids: Union[str, List[str]] = "*",
):

    aiplatform.init(project=project, location=location)

    my_entity_type = aiplatform.featurestore.EntityType(
        entity_type_name=entity_type_id, featurestore_id=featurestore_id
    )

    my_dataframe = my_entity_type.read(entity_ids=entity_ids, feature_ids=feature_ids)

    return my_dataframe

Java

在試用這個範例之前,請先按照Java使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 Vertex AI Java API 參考說明文件

如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。


import com.google.cloud.aiplatform.v1.EntityTypeName;
import com.google.cloud.aiplatform.v1.FeatureSelector;
import com.google.cloud.aiplatform.v1.FeaturestoreOnlineServingServiceClient;
import com.google.cloud.aiplatform.v1.FeaturestoreOnlineServingServiceSettings;
import com.google.cloud.aiplatform.v1.IdMatcher;
import com.google.cloud.aiplatform.v1.ReadFeatureValuesRequest;
import com.google.cloud.aiplatform.v1.ReadFeatureValuesResponse;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;

public class ReadFeatureValuesSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    // Feature Store ID
    String featurestoreId = "YOUR_FEATURESTORE_ID";
    // Entity Type ID
    String entityTypeId = "YOUR_ENTITY_TYPE_ID";
    // Entity ID
    String entityId = "YOUR_ENTITY_ID";
    // Features to read with batch or online serving.
    List<String> featureSelectorIds = Arrays.asList("title", "genres", "average_rating");
    String location = "us-central1";
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    int timeout = 300;

    readFeatureValuesSample(
        project,
        featurestoreId,
        entityTypeId,
        entityId,
        featureSelectorIds,
        location,
        endpoint,
        timeout);
  }

  /*
   * Reads Feature values of a specific entity of an EntityType.
   * See: https://cloud.google.com/vertex-ai/docs/featurestore/serving-online
   */
  public static void readFeatureValuesSample(
      String project,
      String featurestoreId,
      String entityTypeId,
      String entityId,
      List<String> featureSelectorIds,
      String location,
      String endpoint,
      int timeout)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    FeaturestoreOnlineServingServiceSettings featurestoreOnlineServiceSettings =
        FeaturestoreOnlineServingServiceSettings.newBuilder().setEndpoint(endpoint).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (FeaturestoreOnlineServingServiceClient featurestoreOnlineServiceClient =
        FeaturestoreOnlineServingServiceClient.create(featurestoreOnlineServiceSettings)) {
      ReadFeatureValuesRequest readFeatureValuesRequest =
          ReadFeatureValuesRequest.newBuilder()
              .setEntityType(
                  EntityTypeName.of(project, location, featurestoreId, entityTypeId).toString())
              .setEntityId(entityId)
              .setFeatureSelector(
                  FeatureSelector.newBuilder()
                      .setIdMatcher(IdMatcher.newBuilder().addAllIds(featureSelectorIds)))
              .build();

      ReadFeatureValuesResponse readFeatureValuesResponse =
          featurestoreOnlineServiceClient.readFeatureValues(readFeatureValuesRequest);
      System.out.println("Read Feature Values Response" + readFeatureValuesResponse);
    }
  }
}

Node.js

在試用這個範例之前,請先按照Node.js使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 Vertex AI Node.js API 參考說明文件

如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const project = 'YOUR_PROJECT_ID';
// const featurestoreId = 'YOUR_FEATURESTORE_ID';
// const entityTypeId = 'YOUR_ENTITY_TYPE_ID';
// const entityId = 'ENTITY_ID_TO_SERVE';
// const location = 'YOUR_PROJECT_LOCATION';
// const apiEndpoint = 'YOUR_API_ENDPOINT';
// const timeout = <TIMEOUT_IN_MILLI_SECONDS>;

// Imports the Google Cloud Featurestore Service Client library
const {FeaturestoreOnlineServingServiceClient} =
  require('@google-cloud/aiplatform').v1;

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: apiEndpoint,
};

// Instantiates a client
const featurestoreOnlineServingServiceClient =
  new FeaturestoreOnlineServingServiceClient(clientOptions);

async function readFeatureValues() {
  // Configure the entityType resource
  const entityType = `projects/${project}/locations/${location}/featurestores/${featurestoreId}/entityTypes/${entityTypeId}`;

  const featureSelector = {
    idMatcher: {
      ids: ['age', 'gender', 'liked_genres'],
    },
  };

  const request = {
    entityType: entityType,
    entityId: entityId,
    featureSelector: featureSelector,
  };

  // Read Feature Values Request
  const [response] =
    await featurestoreOnlineServingServiceClient.readFeatureValues(request, {
      timeout: Number(timeout),
    });

  console.log('Read feature values response');
  console.log('Raw response:');
  console.log(JSON.stringify(response, null, 2));
}
readFeatureValues();

從多個實體提供值

為特定實體類型提供一或多個實體的特徵值。 為提升效能,請使用 streamingReadFeatureValues 方法,而非向 readFeatureValues 方法傳送平行要求。

REST

如要從多個實體取得特徵值,請使用 featurestores.entityTypes.streamingReadFeatureValues 方法傳送 POST 要求。

以下範例會取得兩個不同實體的兩個不同特徵的最新值。請注意,針對 ids 欄位,您可以指定 ["*"],而非特徵 ID,藉此選取實體的所有特徵。

使用任何要求資料之前,請先替換以下項目:

  • LOCATION_ID:建立特徵商店的區域。例如:us-central1
  • PROJECT_ID:您的專案 ID
  • FEATURESTORE_ID:特徵商店的 ID。
  • ENTITY_TYPE_ID:實體類型 ID。
  • ENTITY_ID:要取得特徵值的實體 ID。
  • FEATURE_ID:要取得值的特徵 ID。

HTTP 方法和網址:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:streamingReadFeatureValues

JSON 要求主體:

{
  "entityIds": ["ENTITY_ID_1", "ENTITY_ID_2"],
  "featureSelector": {
    "idMatcher": {
      "ids": ["FEATURE_ID_1", "FEATURE_ID_2"]
    }
  }
}

如要傳送要求,請選擇以下其中一個選項:

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/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:streamingReadFeatureValues"

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/v1/projects/PROJECT_ID/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID:streamingReadFeatureValues" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應:

[{
  "header": {
    "entityType": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID",
    "featureDescriptors": [
      {
        "id": "FEATURE_ID_1"
      },
      {
        "id": "FEATURE_ID_2"
      }
    ]
  }
},
{
  "entityView": {
    "entityId": "ENTITY_ID_1",
    "data": [
      {
        "value": {
          "VALUE_TYPE_1": "FEATURE_VALUE_A",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      },
      {
        "value": {
          "VALUE_TYPE_2": "FEATURE_VALUE_B",
          "metadata": {
            "generateTime": "2019-10-28T15:38:10Z"
          }
        }
      }
    ]
  }
},
{
  "entityView": {
    "entityId": "ENTITY_ID_2",
    "data": [
      {
        "value": {
          "VALUE_TYPE_1": "FEATURE_VALUE_C",
          "metadata": {
            "generateTime": "2019-10-28T21:21:37Z"
          }
        }
      },
      {
        "value": {
          "VALUE_TYPE_2": "FEATURE_VALUE_D",
          "metadata": {
            "generateTime": "2019-10-28T21:21:37Z"
          }
        }
      }
    ]
  }
}]

其他語言

您可以安裝及使用下列 Vertex AI 用戶端程式庫,呼叫 Vertex AI API。Cloud 用戶端程式庫會使用每種支援語言的自然慣例與樣式,提供最佳開發人員體驗。

後續步驟