本文档介绍了如何使用 Vertex AI SDK for ABAP 调用嵌入模型以生成文本和多模态嵌入。
嵌入本质上是数字代码，用于以捕捉它们之间的关联方式来表示文本、图片或视频。应用使用这些代码来理解和生成语言，甚至可以识别特定内容中最复杂的含义和关系。该过程的工作原理是将文本、图片和视频转换为数字列表（称为向量），这些向量旨在有效捕捉原始内容的含义。
文本嵌入的一些常见应用场景包括：
- 语义搜索：按语义相似度排序搜索文本。
- 分类：返回文本属性与给定文本类似的项的类。
- 聚类：将文本属性与给定文本类似的项聚类。
- 离群值检测：返回文本属性与给定文本相关性最低的项。
- 对话界面：将可能生成类似回复（例如在对话级嵌入空间中）的句子组聚类。
借助 Vertex AI SDK for ABAP，您可以使用 SDK 随附的类和方法从 ABAP 应用逻辑生成嵌入。该 SDK 还提供了一些开箱即用的方法，用于将生成的嵌入推送到以下数据存储区：
- Cloud Storage：您可以使用 Cloud Storage 存储桶中的嵌入来构建向量索引和执行 Vector Search。
- BigQuery：您可以将 BigQuery 数据集中的嵌入式数据用作企业数据的向量数据库。
您还可以将嵌入发布到可路由到 BigQuery 数据集或订阅者系统的 Pub/Sub 主题。
准备工作
在将 Vertex AI SDK for ABAP 与嵌入模型搭配使用之前，请确保您或您的管理员已满足以下前提条件：
- 在 Google Cloud 项目中启用了 Vertex AI API。
- 在 SAP 环境中安装了 Vertex AI SDK for ABAP。
- 设置身份验证以访问 Vertex AI API。
- 配置了模型生成参数。如需生成嵌入，仅需要以下参数：模型键、模型 ID、Google Cloud 密钥名称、Google Cloud 区域位置 ID 和 LLM 的发布商 ID。
生成嵌入
本部分介绍了如何使用 Vertex AI SDK for ABAP 生成嵌入。
实例化多模态嵌入类
如需使用文本或多模态输入调用 Vertex AI 多模态嵌入模型，您可以使用 /GOOG/CL_EMBEDDINGS_MODEL 类。您可以通过传递在模型生成参数中配置的模型键来实例化该类。
DATA(lo_embeddings_model) = NEW /goog/cl_embeddings_model( iv_model_key = 'MODEL_KEY' ).
将 MODEL_KEY 替换为模型密钥名称，该名称在模型生成参数中进行配置。
生成文本嵌入
如需为文本片段生成嵌入，您可以使用 /GOOG/CL_EMBEDDINGS_MODEL 类的 GEN_TEXT_EMBEDDINGS 方法。您还可以选择为输出嵌入指定维度。
DATA(ls_addln_params) = VALUE /goog/cl_embeddings_model=>ty_addln_params(
output_dimensionality = 'DIMENSION' ).
DATA(lt_embeddings) = lo_embeddings_model->gen_text_embeddings(
iv_content = 'INPUT_TEXT'
is_addln_params = ls_addln_params
)->get_vector( ).
替换以下内容：
DIMENSION：可选。输出嵌入的维度。默认尺寸为768。INPUT_TEXT：要生成嵌入的文本。
您还可以使用 SDK 随附的开箱即用模板 /GOOG/CL_EMBEDDINGS_MODEL=>TY_EMBEDDINGS_TEMPLATE 为文本片段生成嵌入。借助此模板，您可以在生成的嵌入文件中捕获企业特定的示意信息以及嵌入信息。
如需根据 /GOOG/CL_EMBEDDINGS_MODEL=>TY_EMBEDDINGS_TEMPLATE 模板为文本片段生成嵌入，您可以使用 GEN_TEXT_EMBEDDINGS_BY_STRUCT 方法。
DATA(ls_embedding_template) = VALUE /goog/cl_embeddings_model=>ty_embeddings_template(
id = ENTITY_ID
content = INPUT_TEXT
source = SOURCE_MODULE ).
DATA(ls_addln_params) = VALUE /goog/cl_embeddings_model=>ty_addln_params(
output_dimensionality = 'DIMENSION' ).
DATA(lt_embeddings) = lo_embeddings_model->gen_text_embeddings_by_struct(
is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->get_vector_by_struct( ).
替换以下内容：
ENTITY_ID：嵌入记录的实体 ID。INPUT_TEXT：要生成嵌入的文本。SOURCE_MODULE：嵌入内容的源模块。DIMENSION：可选。输出嵌入的维度。默认尺寸为768。
生成嵌入图片
如需为输入图片生成嵌入，您可以使用 /GOOG/CL_EMBEDDINGS_MODEL 类的 GEN_IMAGE_EMBEDDINGS 方法。您可以传递图片的原始数据，也可以传递图片文件的 Cloud Storage URI。您还可以选择为图片指定上下文文本，并为输出嵌入指定维度。
DATA(ls_image) = VALUE /goog/cl_embeddings_model=>ty_image( gcs_uri = 'IMAGE_URI' ).
DATA(lt_embeddings) = lo_embeddings_model->gen_image_embeddings( iv_image = ls_image
iv_contextual_text = 'CONTEXTUAL_TEXT'
)->get_vector( ).
替换以下内容：
IMAGE_URI：要为其获取嵌入的目标图片的 Cloud Storage URI。CONTEXTUAL_TEXT：可选。为嵌入式模型提供图片内容的更多背景信息和含义。
您还可以使用 SDK 随附的开箱即用模板 /GOOG/CL_EMBEDDINGS_MODEL=>TY_EMBEDDINGS_TEMPLATE 为图片生成嵌入。借助此模板，您可以在生成的嵌入文件中捕获企业特定的示意信息以及嵌入信息。
如需根据 /GOOG/CL_EMBEDDINGS_MODEL=>TY_EMBEDDINGS_TEMPLATE 模板为图片生成嵌入，您可以使用 GEN_IMAGE_EMBEDDINGS_BY_STRUCT 方法。
DATA(ls_image) = VALUE /goog/cl_embeddings_model=>ty_image( gcs_uri = 'IMAGE_URI' ).
DATA(ls_embedding_template) = VALUE /goog/cl_embeddings_model=>ty_embeddings_template(
id = ENTITY_ID
content = INPUT_TEXT
source = SOURCE_MODULE ).
DATA(lt_embeddings) = lo_embeddings_model->gen_image_embeddings_by_struct(
iv_image = ls_image
is_input = ls_embedding_template
)->get_vector_by_struct( ).
替换以下内容：
IMAGE_URI：要为其获取嵌入的目标图片的 Cloud Storage URI。ENTITY_ID：嵌入记录的实体 ID。INPUT_TEXT：要生成嵌入的文本。SOURCE_MODULE：嵌入内容的源模块。
如需检索上下文文本的嵌入，请使用以下代码：
DATA(lt_context_embeddings) = lo_embeddings_model->get_context_text_vector( ).
此选项仅适用于创建单个图片嵌入。
生成视频嵌入
如需为输入视频生成嵌入，您可以使用 /GOOG/CL_EMBEDDINGS_MODEL 类的 GET_VIDEO_EMBEDDINGS 方法。您可以传递视频文件的 Cloud Storage URI，以及可选的开始和结束偏移时间（以秒为单位）。您还可以选择为视频指定上下文文本，并为输出嵌入指定维度。
DATA(ls_video) = VALUE /goog/cl_embeddings_model=>ty_video( gcs_uri = 'VIDEO_URI' ).
DATA(lt_embeddings) = lo_embeddings_model->gen_video_embeddings( iv_video = ls_video
iv_contextual_text = 'CONTEXTUAL_TEXT'
iv_dimension = 'DIMENSION'
)->get_vector( ).
VIDEO_URI：要为其获取嵌入的目标视频的 Cloud Storage URI。CONTEXTUAL_TEXT：可选。为视频内容提供额外的上下文和含义，以便嵌入模型使用。DIMENSION：可选。输出嵌入的维度。可用的维度包括：128、256、512和1408（默认）。
GET_VECTOR 方法仅返回视频的第一个片段的嵌入。
如需检索上下文文本的嵌入，请使用以下代码：
DATA(lt_context_embeddings) = lo_embeddings_model->get_context_text_vector( ).
此选项仅适用于单个视频嵌入创建。
收集所有生成的嵌入
如需在类型为 /GOOG/CL_EMBEDDINGS_MODEL=>TY_T_EMBEDDINGS_TEMPLATE 的内部表中收集所有生成的嵌入，您可以将 /GOOG/CL_EMBEDDINGS_MODEL 类的 COLLECT 方法与 GEN_TEXT_EMBEDDINGS_BY_STRUCT 和 GEN_IMAGE_EMBEDDINGS_BY_STRUCT 方法结合使用。
如果您需要为一系列项 (text/image) 生成嵌入，并且希望在循环迭代中生成嵌入，并在迭代后在内部表中一次性获取所有嵌入，此方法会非常有用。方法 GET_VECTOR_BY_TABLE 可用于获取嵌入的最终内部表格。
LOOP AT ....
lo_embeddings_model->gen_text_embeddings_by_struct( is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->collect( ).
ENDLOOP.
DATA(lt_embeddings) = lo_embeddings_model->get_vector_by_table( ).
将嵌入发送到数据存储区
您可以使用 SDK 随附的模板将生成的嵌入发送到 Cloud Storage 存储桶或 BigQuery 数据集。
将嵌入存储在 Cloud Storage 中
如需将生成的嵌入发送到 Cloud Storage 存储桶，您可以使用 /GOOG/CL_EMBEDDINGS_MODEL 类的 SEND_STRUCT_TO_GCS 方法。
在将嵌入发送到 Cloud Storage 之前，请确保您有一个要将嵌入发送到的 Cloud Storage 存储桶。
将单个嵌入发送到 Cloud Storage 存储桶
以下代码示例演示了如何将单个图片嵌入发送到 Cloud Storage 存储桶：
DATA(ls_image) = VALUE /goog/cl_embeddings_model=>ty_image( gcs_uri = 'IMAGE_URI' ).
lo_embeddings_model->gen_image_embeddings_by_struct( iv_image = ls_image
is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->send_struct_to_gcs( iv_key = 'CLIENT_KEY'
iv_bucket_name = 'BUCKET_NAME'
iv_file_name = 'FILE_NAME' ).
替换以下内容：
IMAGE_URI：要为其获取嵌入的目标图片的 Cloud Storage URI。CLIENT_KEY：用于调用 Cloud Storage API 的客户端密钥。BUCKET_NAME：目标 Cloud Storage 存储桶名称。FILE_NAME：嵌入文件名。
将收集的嵌入式数据发送到 Cloud Storage 存储桶
以下代码示例演示了如何将收集的嵌入数据发送到 Cloud Storage 存储桶：
LOOP AT ....
lo_embeddings_model->gen_text_embeddings_by_struct( is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->collect( ).
ENDLOOP.
lo_embeddings_model->send_struct_to_gcs( iv_key = 'CLIENT_KEY'
iv_bucket_name = 'BUCKET_NAME'
iv_file_name = 'FILE_NAME' ).
替换以下内容：
CLIENT_KEY：用于调用 Cloud Storage API 的客户端密钥。BUCKET_NAME：目标 Cloud Storage 存储桶名称。FILE_NAME：嵌入文件名。
将嵌入存储在 BigQuery 中
如需将生成的嵌入发送到 BigQuery 数据集，您可以使用 /GOOG/CL_EMBEDDINGS_MODEL 的 SEND_STRUCT_TO_BQ 方法。
在将嵌入发送到 BigQuery 之前，请确保您有一个 BigQuery 数据集和一个要将嵌入发送到的表。
将单个嵌入发送到 BigQuery 数据集
以下代码示例说明了如何将单个图片嵌入发送到 BigQuery 数据集：
lo_embeddings_model->gen_image_embeddings_by_struct( iv_image = ls_image
is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->send_struct_to_bq( iv_key = 'CLIENT_KEY'
iv_dataset_id = 'DATASET_ID'
iv_table_id = 'TABLE_ID' ).
替换以下内容：
CLIENT_KEY：用于调用 BigQuery API 的客户端密钥。DATASET_ID：BigQuery 数据集 ID。TABLE_ID：BigQuery 表 ID。
将收集的嵌入发送到 BigQuery 数据集
以下代码示例说明了如何将收集的嵌入数据发送到 BigQuery 数据集：
LOOP AT ....
lo_embeddings_model->gen_text_embeddings_by_struct( is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->collect( ).
ENDLOOP.
lo_embeddings_model->send_struct_to_bq( iv_key = 'CLIENT_KEY'
iv_dataset_id = 'DATASET_ID'
iv_table_id = 'TABLE_ID' ).
替换以下内容：
CLIENT_KEY：用于调用 BigQuery API 的客户端密钥。DATASET_ID：BigQuery 数据集 ID。TABLE_ID：BigQuery 表 ID。
将嵌入发布到 Pub/Sub 主题
如需将生成的嵌入发布到 Pub/Sub 主题，您可以使用 /GOOG/CL_EMBEDDINGS_MODEL 类的 SEND_STRUCT_TO_PUBSUB 方法。在需要构建自己的自定义流水线来存储嵌入和构建后续业务流程的场景中，此方法非常有用。
在将嵌入发送到 Pub/Sub 主题之前，请确保您有一个要将嵌入发送到的 Pub/Sub 主题。
将单个嵌入发布到 Pub/Sub 主题
以下代码示例演示了如何将单个图片嵌入发布到 Pub/Sub 主题：
lo_embeddings_model->gen_image_embeddings_by_struct( iv_image = ls_image
is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->send_struct_to_pubsub( iv_key = 'CLIENT_KEY'
iv_topic_id = 'TOPIC_ID' ).
替换以下内容：
CLIENT_KEY：用于调用 Pub/Sub API 的客户端密钥。TOPIC_ID：Pub/Sub 主题 ID。
将收集的嵌入发布到 Pub/Sub 主题
以下代码示例说明了如何将收集的嵌入内容发布到 Pub/Sub 主题：
LOOP AT ....
lo_embeddings_model->gen_text_embeddings_by_struct( is_input = ls_embedding_template
is_addln_params = ls_addln_params
)->collect( ).
ENDLOOP.
lo_embeddings_model->send_struct_to_pubsub( iv_key = 'CLIENT_KEY'
iv_topic_id = 'TOPIC_ID' ).
替换以下内容：
CLIENT_KEY：用于调用 Pub/Sub API 的客户端密钥。TOPIC_ID：Pub/Sub 主题 ID。
后续步骤
在 Cloud 论坛上提出问题并与社区讨论 Vertex AI SDK for ABAP。