本文說明如何使用 ABAP 專用的 Vertex AI SDK 叫用嵌入模型，產生文字和多模態嵌入。
嵌入基本上是數字代碼，用來表示文字、圖片或影片，並捕捉它們之間的關聯。應用程式會使用這些程式碼來理解及產生語言，甚至可辨識特定內容中最複雜的意義和關係。這個程序會將文字、圖片和影片轉換為數字清單，也就是向量，以便有效擷取原始內容的意思。
文字嵌入的常見用途包括：
- 語意搜尋：搜尋按語意相似度排序的文字。
- 分類：傳回文字屬性與指定文字相似的項目類別。
- 分群：依據特定文字，將文字屬性相似的項目分群。
- 異常值偵測：傳回文字屬性與指定文字最不相關的項目。
- 對話式介面：將可能產生類似回覆的句子群組歸類，例如對話層級的嵌入空間。
使用 ABAP 適用的 Vertex AI SDK，您可以使用 SDK 隨附的類別和方法，從 ABAP 應用程式邏輯產生嵌入資料。SDK 也提供即用即付的方法，可將產生的嵌入內容推送至下列資料儲存庫：
- Cloud Storage：您可以使用 Cloud Storage 值區中的嵌入項目，建立向量索引並執行向量搜尋。
- BigQuery：您可以將 BigQuery 資料集的嵌入資料做為企業資料的向量資料庫。
您也可以將嵌入項目發布至 Pub/Sub 主題，並將其路由至 BigQuery 資料集或訂閱者系統。
事前準備
在使用 ABAP 專用的 Vertex AI SDK 搭配嵌入模型前，請確認您或管理員已完成下列先決條件：
- 在 Google Cloud 專案中啟用 Vertex AI API。
- 在 SAP 環境中安裝 ABAP 適用的 Vertex AI SDK。
- 設定驗證，以便存取 Vertex AI API。
- 設定模型產生參數。如要產生嵌入資料，只需要以下參數：模型鍵、模型 ID、Google Cloud 鍵名稱、Google Cloud 區域位置 ID 和 LLM 的發布者 ID。
生成嵌入項目
本節將說明如何使用 ABAP 專用的 Vertex AI SDK 產生嵌入資料。
例項化多模態嵌入類別
如要使用文字或多模態輸入內容叫用 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。
後續步驟
- 瞭解如何使用 ABAP SDK for Google Cloud 的 SAP BTP 版本開發應用程式。
- 歡迎在 Cloud 論壇上提問，並與社群討論 ABAP 專用的 Vertex AI SDK。