使用 Vertex AI Feature Store

SAP BTP edition v1.1

• SAP BTP 版本 v1.1
• 本地或任何云版本 v1.9

本文档介绍了如何使用 Vertex AI Feature Store 通过 Vertex AI SDK for ABAP 执行各种任务，例如同步在线存储区、从在线存储区传送特征，以及使用实体或嵌入式搜索在线特征存储区。

Vertex AI Feature Store 是一项托管式云原生特征存储服务。它允许您在 BigQuery 表或视图中管理特征数据，从而简化了机器学习特征管理和在线传送流程。

在 Vertex AI Feature Store 设置的典型工作流中，您首先需要在 BigQuery 中准备 SAP 数据源，通过创建特征组和特征来注册数据源，然后设置在线存储区和特征视图资源。然后，您可以从特征视图在线传送最新特征值，或在线特征存储区中执行相似度搜索。如需了解如何设置 Vertex AI Feature Store，请参阅 Vertex AI Feature Store。

Vertex AI Feature Store 准备好在线传送后，您可以使用 Vertex AI SDK for ABAP 执行以下操作：

• 为了在模型预测期间为实时传送提供最新且准确的特征值，请将您的在线存储区与 BigQuery 中的特征数据源同步。
• 如需从在线存储区提供特征值以用于实时应用，请从在线存储区传送特征。
• 如需从在线存储区检索在语义上相似或相关的实体的列表，请使用实体或嵌入进行搜索。

准备工作

在将 Vertex AI SDK for ABAP 与 Vertex AI Feature Store 搭配使用之前，请确保您或您的管理员已满足以下前提条件：

• 在 Google Cloud 项目中启用了 Vertex AI API。
• 在 SAP 环境中安装了 Vertex AI SDK for ABAP。
• 设置身份验证以访问 Vertex AI API。
• 设置在线特征传送。如需了解如何创建和使用在线存储区，以通过 Vertex AI Feature Store 在端到端工作流中托管和传送 BigQuery 中的数据，请参阅Vertex AI Feature Store 的 Jupyter Notebook 教程。

为 Vertex AI Feature Store 实例化 ABAP 类

如需在 ABAP 应用中使用 Vertex AI Feature Store，您需要实例化类 /GOOG/CL_FEATURE_STORE。

DATA(lo_client) = NEW /goog/cl_feature_store(
                          iv_key_name         = 'CLIENT_KEY'
                          iv_location         = 'LOCATION_ID'
                          iv_feature_store_id = 'FEATURE_ONLINE_STORE_NAME' ).

替换以下内容：

• CLIENT_KEY：为身份验证而配置的客户端密钥。
• LOCATION_ID：在线存储区所在的区域，例如 us-central1。
• FEATURE_ONLINE_STORE_NAME：包含特征视图的在线存储区的名称。

同步在线存储区

为了确保您的在线存储区在模型预测期间拥有最新且准确的特征值，以便实时传送，您需要将在线存储区中的特征视图资源与 BigQuery 中的特征数据源同步。

准备工作

由于您是通过区域端点访问 Vertex AI Feature Store，因此需要创建通信系统、通信安排，并相应地配置客户端密钥。

1. 访问安装了 ABAP SDK for Google Cloud 的 BTP ABAP 系统的 SAP Fiori launchpad。

2. 前往 All spaces > Administration > Communication Management。

3. 创建通信系统：

   1. 打开 Communication Systems 应用。
   2. 点击 New（新建）。

   3. 在显示的 New Communication System 对话框中，为以下字段输入值：

      • System ID：输入系统 ID。
      • System name：输入系统名称。

   4. 点击创建。

   5. 在主机名字段中，输入区域性端点的网址。例如，如果您的 Vertex AI Feature Store 位于 us-east1，则目标主机的端点为 us-east1-aiplatform.googleapis.com。如需了解区域性端点，请参阅服务端点。

   6. 在端口字段中，输入 443。

   7. 在 Users for Outbound Communication 标签页上，点击 Add。

   8. 对于 Authentication method（身份验证方法）字段，请选择 None（无）。

   9. 点击保存。

4. 创建通信安排：

   1. 打开 Communication Arrangement 应用。
   2. 点击 New（新建）。

   3. 在显示的 New Communication Arrangement 对话框中，为以下字段输入值：

      • Scenario：选择 Authentication using Workload Identity Federation (/GOOG/COM_SDK_SRV)。
      • Arrangement name：输入通信安排的名称。

   4. 点击创建。

   5. 对于显示的通信安排条目，请在 Communication System 字段中，选择您在上一步中创建的通信系统。

   6. 点击保存。

5. 创建客户端密钥和通信映射：

   1. 前往包含用于 SDK 配置的 SAP Fiori 应用的空间。
   2. 打开 Google SDK: Main Configuration 应用。
   3. 点击创建。
   4. 在显示的 Create 对话框中，输入客户端密钥名称。
   5. 点击继续。

   6. 为以下字段输入值：

      • Service account：输入授予了 Google Cloud API 访问权限的服务账号。
      • Project ID：输入已启用 Google Cloud API 的 Google Cloud 项目的项目 ID。如需了解项目 ID，请参阅标识项目。
      • Project number：输入您已启用 Google Cloud API 的 Google Cloud 项目的项目编号。如需了解项目编号，请参阅标识项目。
      • Authentication type：选择 W (Workload Identity Federation)。

   7. 对于服务名称默认条目为“authentication”的通信映射，请提供您为基于 WIF 的身份验证设置的通信安排

   8. 向通信映射中再添加一个条目，并将服务选择为 aiplatform:v1，然后提供您刚刚创建的通信安排。

   9. 点击创建。系统会显示一个对话框，确认您同意依照标准 Google Cloud 条款使用 ABAP SDK for Google Cloud。

   10. 如需验证身份验证配置，请点击 Check connection。条目的绿色对勾标记表示配置成功。

       如果出现任何错误，请参阅问题排查指南，了解如何解决常见错误。

同步 Vertex AI Feature Store

如需在特征视图中启动数据同步，请使用 SYNC_FEATURE_DATA_TO_FS 方法。

DATA(lv_feature_view_sync_id) = lo_client->sync_feature_data_to_fs(
                                             iv_feature_view_id = 'FEATURE_VIEW_NAME'
                                        )->get_feature_sync_id( ).

将 FEATURE_VIEW_NAME 替换为要为其启动数据同步的特征视图的名称。

此方法会返回特征视图同步 ID，可用于检查同步状态。

获取 Vertex AI Feature Store 同步的状态

如需获取 Vertex AI Feature Store 同步的状态，您可以使用 GET_FEATURE_SYNC_STATUS 方法。

DATA(ls_status) = lo_client->get_feature_sync_status(
                               iv_feature_view_id     = 'FEATURE_VIEW_NAME'
                               iv_feature_sync_id     = 'FEATURE_VIEW_SYNC_ID'
              )->get_feature_sync_status( ).

替换以下内容：

• FEATURE_VIEW_NAME：您要检查其同步状态的特征视图的名称。

• FEATURE_VIEW_SYNC_ID：从同步 Vertex AI Feature Store 收到的特征视图同步 ID。

  此方法会返回以下某个状态以及错误消息（如果有）：C: Complete、R: Running 或 F: Failed

从在线存储区传送特征

您可以从在线存储区提供特征值，以用于实时应用，例如产品推荐。根据您为在线存储区配置的在线传送类型，您可以通过以下任一方式提供特征值：

• 使用 Bigtable 在线传送提取特征值。
• 使用优化的公共端点提供在线值来提取特征值。
• 使用具有 Private Service Connect 端点的优化在线传送提取特征值。

如需详细了解如何提供特征值，请参阅从在线存储区提供特征。

准备工作

您需要先从在线存储区详细信息中检索公共端点域名，然后才能开始从在线存储区提供特征值。之后，您需要创建通信系统和通信安排，并使用 Google SDK: Main Configuration SAP Fiori 应用在客户端密钥配置中对其进行配置。

1. 如需检索公共端点，请在您选择的本地软件包中创建 ZCL_GET_FEATURE_STORE_PUB_EP。您需要传递有效的客户端密钥，以及 Vertex AI Feature Store 的存储空间 ID 和位置。

   CLASS zcl_get_feature_store_pub_ep DEFINITION
   PUBLIC FINAL
   CREATE PUBLIC.
   PUBLIC SECTION.
      INTERFACES if_oo_adt_classrun.
   ENDCLASS.
   CLASS zcl_get_feature_store_pub_ep IMPLEMENTATION.
   METHOD if_oo_adt_classrun~main.
      DATA lv_ckey        TYPE /goog/keyname.
      DATA lv_location_id TYPE string.
      DATA lv_fsid        TYPE string.
      DATA lv_project_id  TYPE string.
      DATA lv_msg         TYPE string.
   
      "TODO:Developer - Pass relevant values
      lv_ckey = 'CLIENT_KEY'.
      lv_fsid = 'FEATURE_ONLINE_STORE_NAME'.
      lv_location_id = 'LOCATION_ID'.
      TRY.
         DATA(lo_aip) = NEW  /goog/cl_aiplatform_v1( iv_key_name = lv_ckey ).
         lv_project_id = lo_aip->gv_project_id.
         " Call API method: aiplatform.projects.locations.featureOnlineStores.get
         lo_aip->get_feature_online_stores( EXPORTING iv_p_projects_id              = lv_project_id
                                                      iv_p_locations_id             = lv_location_id
                                                      iv_p_feature_online_stores_id = lv_fsid
                                             IMPORTING es_output                     = DATA(ls_output)
                                                      ev_ret_code                   = DATA(lv_ret_code)
                                                      ev_err_text                   = DATA(lv_err_text) ).
         IF lo_aip->is_success( lv_ret_code ) = abap_true.
            out->write( | Public endpoint is| ).
            out->write( ls_output-dedicated_serving_endpoint-public_endpoint_domain_name ).
         ENDIF.
         CATCH /goog/cx_sdk INTO DATA(lo_cx_sdk).
         lv_msg = lo_cx_sdk->get_text( ).
         out->write( |Exception occurred, reason: { lv_msg }| ).
      ENDTRY.
   ENDMETHOD.
   ENDCLASS.
   

2. 激活并执行 ZCL_GET_FEATURE_STORE_PUB_EP 类。

   输出（即在线商店的公共端点）采用以下格式：

   xxxxxxxxxx.LOCATION_ID-PROJECT_ID.featurestore.vertexai.goog
   

   此输出包括以下值：

   • LOCATION_ID：您的在线商店所在的区域。
   • PROJECT_ID：您的网店所在的 Google Cloud 项目的项目 ID。

3. 访问安装了 ABAP SDK for Google Cloud 的 BTP ABAP 系统的 SAP Fiori launchpad。

4. 前往 All spaces > Administration > Communication Management。

5. 创建通信系统：

   1. 打开 Communication Systems 应用。
   2. 点击 New（新建）。

   3. 在显示的 New Communication System 对话框中，为以下字段输入值：

      • System ID：输入系统 ID。
      • System name：输入系统名称。

   4. 点击创建。

   5. 在主机名称字段中，输入您在上一步中通过执行 ZCL_GET_FEATURE_STORE_PUB_EP 类检索到的公共端点。

   6. 在端口字段中，输入 443。

   7. 前往 Users for Outbound Communication 标签页，然后点击 Add。

   8. 在身份验证方法字段中，选择无。

   9. 点击保存。

6. 创建通信安排：

   1. 打开 Communication Arrangements 应用。
   2. 点击 New（新建）。

   3. 在显示的 New Communication Arrangement 对话框中，为以下字段输入值：

      • Scenario：选择 Authentication using Workload Identity Federation (/GOOG/COM_SDK_SRV)。
      • Arrangement name：输入通信安排的名称。

   4. 点击创建。

   5. 对于显示的通信安排条目，请在 Communication System 字段中，选择您在上一步中创建的通信系统。

   6. 点击保存。

7. 创建客户端密钥和通信映射：

   1. 前往包含用于 SDK 配置的 SAP Fiori 应用的空间。
   2. 打开 Google SDK: Main Configuration 应用。
   3. 点击创建。
   4. 在显示的 Create 对话框中，输入客户端密钥名称。
   5. 点击继续。

   6. 输入以下详细信息：

      • Service account：输入授予了 Google Cloud API 访问权限的服务账号。
      • Project ID：输入已启用 Google Cloud API 的 Google Cloud 项目的项目 ID。如需了解项目 ID，请参阅标识项目。
      • Project number：输入您已启用 Google Cloud API 的 Google Cloud 项目的项目编号。如需了解项目编号，请参阅标识项目。
      • Authentication type：选择 W (Workload Identity Federation)。

   7. 对于服务名称默认条目为“authentication”的通信映射，请提供您为基于 WIF 的身份验证设置的通信安排

   8. 向通信映射中再添加一个条目，并将服务选择为 aiplatform:v1，然后提供您刚刚创建的通信安排。

   9. 点击创建。系统会显示一个对话框，确认您同意依照标准 Google Cloud 条款使用 ABAP SDK for Google Cloud。

   10. 如需验证身份验证配置，请点击 Check connection。条目的绿色对勾标记表示配置成功。

       如果出现任何错误，请参阅问题排查指南，了解如何解决常见错误。

8. 确认您的通信映射包含以下三个条目：

   服务名称	通信场景	通信安排
   authentication	/GOOG/SDK_COM_WIF	您为 XSUAA 服务创建的通信安排。
   aiplatform:v1	/GOOG/COM_SDK_SRV	您使用包含 AI PLATFORM 的区域端点的通信系统设置的通信安排。
   apiinvoker:v1	/GOOG/COM_SDK_SRV	您在上一步中为 Vertex AI Feature Store 传送服务的公共端点使用通信系统设置的通信安排。

提取特征照值

在 Vertex AI Feature Store 中，实体是指您要跟踪特征的项，例如客户、产品或任何其他数据点。每个实体都与一组特征及其对应的值相关联。

如需通过指定单个实体 ID 来提取特征值，请使用 SERVE_FEATURE_VALUES 方法。

DATA(lt_features) = lo_client->serve_feature_values(
                         iv_feature_view_id = 'FEATURE_VIEW_NAME'
                             it_entity_id       = 'ENTITY_ID'
                )->get_features( ).

替换以下内容：

• FEATURE_VIEW_NAME：要从中提供特征值的特征视图的名称。
• ENTITY_ID：要从中传送最新特征值的特征记录中的 ID 列值。或者，您也可以提供一个 parts 数组来构建实体 ID。确保 ID 列的顺序与特征视图中定义的顺序相同。

搜索近似最近邻

对于为优化在线传送创建的在线存储区，您可以执行向量相似性搜索来检索在语义上相似或相关的实体（也称为近似最近邻）的列表。您可以根据实体 ID 或嵌入搜索近似最近邻。

准备工作

您需要先从在线存储区详细信息中检索公共端点域名，然后才能开始从在线存储区提供特征值。之后，您需要创建通信系统和通信安排，并使用 Google SDK: Main Configuration SAP Fiori 应用在客户端密钥配置中对其进行配置。

1. 如需检索公共端点，请在您选择的本地软件包中创建 ZCL_GET_FEATURE_STORE_PUB_EP。您需要传递有效的客户端密钥，以及 Vertex AI Feature Store 的存储空间 ID 和位置。

   CLASS zcl_get_feature_store_pub_ep DEFINITION
   PUBLIC FINAL
   CREATE PUBLIC.
   PUBLIC SECTION.
      INTERFACES if_oo_adt_classrun.
   ENDCLASS.
   CLASS zcl_get_feature_store_pub_ep IMPLEMENTATION.
   METHOD if_oo_adt_classrun~main.
      DATA lv_ckey        TYPE /goog/keyname.
      DATA lv_location_id TYPE string.
      DATA lv_fsid        TYPE string.
      DATA lv_project_id  TYPE string.
      DATA lv_msg         TYPE string.
   
      "TODO:Developer - Pass relevant values
      lv_ckey = 'CLIENT_KEY'.
      lv_fsid = 'FEATURE_ONLINE_STORE_NAME'.
      lv_location_id = 'LOCATION_ID'.
      TRY.
         DATA(lo_aip) = NEW  /goog/cl_aiplatform_v1( iv_key_name = lv_ckey ).
         lv_project_id = lo_aip->gv_project_id.
         " Call API method: aiplatform.projects.locations.featureOnlineStores.get
         lo_aip->get_feature_online_stores( EXPORTING iv_p_projects_id              = lv_project_id
                                                      iv_p_locations_id             = lv_location_id
                                                      iv_p_feature_online_stores_id = lv_fsid
                                             IMPORTING es_output                     = DATA(ls_output)
                                                      ev_ret_code                   = DATA(lv_ret_code)
                                                      ev_err_text                   = DATA(lv_err_text) ).
         IF lo_aip->is_success( lv_ret_code ) = abap_true.
            out->write( | Public endpoint is| ).
            out->write( ls_output-dedicated_serving_endpoint-public_endpoint_domain_name ).
         ENDIF.
         CATCH /goog/cx_sdk INTO DATA(lo_cx_sdk).
         lv_msg = lo_cx_sdk->get_text( ).
         out->write( |Exception occurred, reason: { lv_msg }| ).
      ENDTRY.
   ENDMETHOD.
   ENDCLASS.
   

2. 激活并执行 ZCL_GET_FEATURE_STORE_PUB_EP 类。

   输出（即在线商店的公共端点）采用以下格式：

   xxxxxxxxxx.LOCATION_ID-PROJECT_ID.featurestore.vertexai.goog
   

   此输出包括以下值：

   • LOCATION_ID：您的在线商店所在的区域。
   • PROJECT_ID：您的网店所在的 Google Cloud 项目的项目 ID。

3. 访问安装了 ABAP SDK for Google Cloud 的 BTP ABAP 系统的 SAP Fiori launchpad。

4. 前往 All spaces > Administration > Communication Management。

5. 创建通信系统：

   1. 打开 Communication Systems 应用。
   2. 点击 New（新建）。

   3. 在显示的 New Communication System 对话框中，为以下字段输入值：

      • System ID：输入系统 ID。
      • System name：输入系统名称。

   4. 点击创建。

   5. 在主机名称字段中，输入您在上一步中通过执行 ZCL_GET_FEATURE_STORE_PUB_EP 类检索到的公共端点。

   6. 在端口字段中，输入 443。

   7. 前往 Users for Outbound Communication 标签页，然后点击 Add。

   8. 在身份验证方法字段中，选择无。

   9. 点击保存。

6. 创建通信安排：

   1. 打开 Communication Arrangements 应用。
   2. 点击 New（新建）。

   3. 在显示的 New Communication Arrangement 对话框中，为以下字段输入值：

      • Scenario：选择 Authentication using Workload Identity Federation (/GOOG/COM_SDK_SRV)。
      • Arrangement name：输入通信安排的名称。

   4. 点击创建。

   5. 对于显示的通信安排条目，请在 Communication System 字段中，选择您在上一步中创建的通信系统。

   6. 点击保存。

7. 创建客户端密钥和通信映射：

   1. 前往包含用于 SDK 配置的 SAP Fiori 应用的空间。
   2. 打开 Google SDK: Main Configuration 应用。
   3. 点击创建。
   4. 在显示的 Create 对话框中，输入客户端密钥名称。
   5. 点击继续。

   6. 输入以下详细信息：

      • Service account：输入授予了 Google Cloud API 访问权限的服务账号。
      • Project ID：输入已启用 Google Cloud API 的 Google Cloud 项目的项目 ID。如需了解项目 ID，请参阅标识项目。
      • Project number：输入您已启用 Google Cloud API 的 Google Cloud 项目的项目编号。如需了解项目编号，请参阅标识项目。
      • Authentication type：选择 W (Workload Identity Federation)。

   7. 对于服务名称默认条目为“authentication”的通信映射，请提供您为基于 WIF 的身份验证设置的通信安排

   8. 向通信映射中再添加一个条目，并将服务选择为 aiplatform:v1，然后提供您刚刚创建的通信安排。

   9. 点击创建。系统会显示一个对话框，确认您同意依照标准 Google Cloud 条款使用 ABAP SDK for Google Cloud。

   10. 如需验证身份验证配置，请点击 Check connection。条目的绿色对勾标记表示配置成功。

       如果出现任何错误，请参阅问题排查指南，了解如何解决常见错误。

8. 确认您的通信映射包含以下三个条目：

   服务名称	通信场景	通信安排
   authentication	/GOOG/SDK_COM_WIF	您为 XSUAA 服务创建的通信安排。
   aiplatform:v1	/GOOG/COM_SDK_SRV	您使用包含 AI PLATFORM 的区域端点的通信系统设置的通信安排。
   apiinvoker:v1	/GOOG/COM_SDK_SRV	您在上一步中为 Vertex AI Feature Store 传送的公共端点使用通信系统设置的通信安排。

检索嵌入的最近邻匹配项

您可以通过指定嵌入来搜索语义相关的实体。

如需搜索嵌入的最近邻，请使用 SEARCH_USING_EMBEDDINGS 方法发送请求。

DATA(lt_embeddings) = VALUE /goog/cl_aiplatform_v1=>ty_t_/goog/num_float( EMBEDDING_DATA ).

DATA(lt_neighbours) = lo_client->search_using_embeddings(
  EXPORTING
    iv_feature_view_id = 'FEATURE_VIEW_NAME'
    it_embeddings      = lt_embeddings
    is_search_params   = VALUE #( neighbor_count     = 'NEIGHBOR_COUNT'
                                  return_full_entity = 'RETURN_FULL_ENTITY' )
)->get_neighbours( ).

替换以下内容：

• EMBEDDING_DATA：要为其检索近似最近邻匹配项的嵌入。嵌入由浮点数值数组表示。
• FEATURE_VIEW_NAME：您要在其中搜索近似最近邻匹配项的特征视图的名称。
• NEIGHBOR_COUNT：要检索的近似最近邻的数量。
• RETURN_FULL_ENTITY：可选。指定要在响应中包含还是排除实体的特征。如需在响应中添加特征以及实体，请输入 ABAP_TRUE。默认值为 ABAP_FALSE。

检索实体的最近邻匹配项

您可以通过指定实体 ID 来搜索在语义上相关的实体。

如需搜索实体 ID 的最近邻，请使用 SEARCH_USING_ENTITY 方法发送请求。

DATA(lt_neighbours) = lo_client->search_using_entity(
  EXPORTING
    iv_feature_view_id = 'FEATURE_VIEW_NAME'
    iv_entity_id       = 'ENTITY_ID'
    is_search_params   = VALUE #( neighbor_count     = 'NEIGHBOR_COUNT'
                                  return_full_entity = 'RETURN_FULL_ENTITY' )
)->get_neighbours( ).

替换以下内容：

• FEATURE_VIEW_NAME：您要在其中搜索近似最近邻匹配项的特征视图的名称。
• ENTITY_ID:：您要检索其近似最近邻匹配项的实体的实体 ID。
• NEIGHBOR_COUNT：要检索的近似最近邻的数量。
• RETURN_FULL_ENTITY：可选。指定要在响应中包含还是排除实体的特征。如需在响应中添加特征以及实体，请输入 ABAP_TRUE。默认值为 ABAP_FALSE。

后续步骤

• 了解使用 SAP BTP 版本的 ABAP SDK for Google Cloud 进行应用开发。
• 在 Cloud 论坛上提出问题并与社区讨论 Vertex AI SDK for ABAP。