使用分區 DML 為文字資料大量產生向量嵌入

本文說明如何使用 SQL 和 Vertex AI 文字嵌入模型，針對儲存在 Spanner 中的文字資料 (STRING 或 JSON) 大量生成及回填向量嵌入。

必要條件

您必須在 Spanner 資料庫中建立含有文字資料 (STRING 或 JSON) 的資料表。如要進一步瞭解如何匯入資料，請參閱 Spanner 匯入及匯出作業總覽。

用途範例

假設您在 Spanner 中有一個結構定義如下的資料表。這個資料表包含數百萬筆記錄。

GoogleSQL 

CREATE TABLE Products (
  product_id INT64 NOT NULL,
  name STRING(MAX),
  description STRING(MAX)
) PRIMARY KEY(product_id);

PostgreSQL

CREATE TABLE Products (
  product_id INT8 NOT NULL,
  name TEXT,
  description TEXT,
  PRIMARY KEY(product_id)
);

您的目標是為這個表格中的 description 欄產生向量嵌入，找出類似項目並推薦給顧客，藉由向量搜尋提升購物體驗。

註冊嵌入模型

GoogleSQL

在 Spanner 資料庫中，使用 Vertex AI 模型端點註冊文字嵌入模型：

CREATE MODEL MODEL_NAME
INPUT(
  content STRING(MAX)
)
OUTPUT(
  embeddings STRUCT<values ARRAY<FLOAT32>>
)
REMOTE OPTIONS(
    endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
  default_batch_size = 5
)

取代下列項目：

  • ：Vertex AI 文字嵌入模型的名稱MODEL_NAME
  • PROJECT：代管 Vertex AI 端點的專案
  • LOCATION：Vertex AI 端點的位置

PostgreSQL

在 PostgreSQL 方言中，不需要註冊模型。 您會將端點名稱直接傳遞至 spanner.ML_PREDICT_ROW 函式呼叫。

如要瞭解最佳做法，請參閱下列內容：

  • 如要維持配額隔離，請使用其他專案中的端點，產生及回填內嵌內容，而非正式版端點。預留正式版端點，用於處理正式版流量。
  • 確認模型端點支援 default_batch_size 的值。 您可以使用查詢提示 @{remote_udf_max_rows_per_rpc=NEW_NUMBER} 覆寫 default_batch_size。如要瞭解各區域的default_batch_size限制，請參閱「取得文字片段的文字嵌入」。
  • 請使用特定模型版本 (例如 @003) 定義端點，而非 @latest。這是因為為同一段文字生成的嵌入向量可能會因使用的模型版本而異；因此，您應避免在同一個資料集中使用不同模型版本生成嵌入項目。此外，更新模型定義陳述式中的模型版本，不會更新已使用這個模型產生的嵌入內容。管理嵌入模型版本的方法之一，是在表格中建立額外資料欄，用來儲存模型版本。
  • GoogleSQL ML.PREDICT 和 PostgreSQL spanner.ML_PREDICT_ROW 函式不支援自訂微調的文字嵌入模型。

測試嵌入模型端對端整合

您可以執行查詢，測試嵌入模型是否已成功設定，並擷取嵌入內容。例如，執行下列查詢：

GoogleSQL 

SELECT embeddings.values
FROM SAFE.ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT description AS content FROM products LIMIT 10)
);

取代下列項目：

  • ：Vertex AI 文字嵌入模型的名稱MODEL_NAME

PostgreSQL

SELECT spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description))))
FROM Products
LIMIT 10;

取代下列項目：

  • PROJECT：代管 Vertex AI 端點的專案
  • LOCATION：Vertex AI 端點的位置
  • ：Vertex AI 文字嵌入模型的名稱MODEL_NAME

更新來源表格，加入其他欄來儲存嵌入內容

接著，更新來源資料表結構定義，加入資料類型為 ARRAY<FLOAT32> 的額外資料欄，用於儲存生成的嵌入內容：

GoogleSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME ARRAY<FLOAT32>;

取代下列項目：

  • TABLE_NAME：來源資料表的名稱
  • EMBEDDING_COLUMN_NAME：要新增生成嵌入的資料欄名稱

PostgreSQL

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[];

取代下列項目：

  • TABLE_NAME：來源資料表的名稱
  • EMBEDDING_COLUMN_NAME：要新增生成嵌入的資料欄名稱

舉例來說，使用 products 表格範例，執行下列指令：

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed ARRAY<FLOAT32>;

PostgreSQL

ALTER TABLE Products
ADD COLUMN desc_embed real[];

您可以新增其他欄，管理嵌入模型版本。

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT64;

PostgreSQL

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT8;

增加 Vertex AI 的配額

您可能需要增加使用文字嵌入模型的區域的 Vertex AI API 配額。如要申請提高配額，請參閱 Vertex AI 配額提高。

詳情請參閱 Vertex AI 配額與限制。

候補廣告嵌入

最後，使用分區 DML 執行下列 UPDATE 陳述式，為文字資料欄產生嵌入內容，並將嵌入內容儲存在資料庫中。您可以連同嵌入項目儲存模型版本。建議您在資料庫流量偏低時執行這項查詢。

GoogleSQL 

UPDATE TABLE_NAME
SET
  TABLE_NAME.EMBEDDING_COLUMN_NAME = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL MODEL_NAME,
      (SELECT TABLE_NAME.DATA_COLUMN_NAME AS content)
    ) @{remote_udf_max_rows_per_rpc=MAX_ROWS}
  ),
  TABLE_NAME.EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

取代下列項目：

  • TABLE_NAME：含有文字資料的資料表名稱
  • EMBEDDING_COLUMN_NAME：要新增生成嵌入的資料欄名稱
  • DATA_COLUMN_NAME：含有文字資料的資料欄名稱
  • MODEL_NAME：Vertex AI 嵌入模型的名稱
  • MAX_ROWS：每個 RPC 的資料列數上限
  • EMBEDDING_VERSION_COLUMN：這個資料欄會管理用於回填嵌入內容的嵌入模型版本
  • MODEL_VERSION：文字嵌入模型版本
  • FILTER_CONDITION：要套用的可分區篩選條件

使用 SAFE.ML.PREDICT 會針對失敗的要求傳回 NULL。您也可以搭配使用 SAFE.ML.PREDICT 和 WHERE embedding_column IS NULL 篩選器，重新執行查詢，而不必計算已計算的欄位嵌入。

PostgreSQL

UPDATE TABLE_NAME
SET
  EMBEDDING_COLUMN_NAME = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', DATA_COLUMN_NAME)))
  ) /*@ remote_udf_max_rows_per_rpc=MAX_ROWS */ ->'predictions'->0->'embeddings'->'values'),
  EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

取代下列項目：

  • TABLE_NAME：含有文字資料的資料表名稱
  • EMBEDDING_COLUMN_NAME：要新增生成嵌入的資料欄名稱
  • DATA_COLUMN_NAME：含有文字資料的資料欄名稱
  • PROJECT：代管 Vertex AI 端點的專案
  • LOCATION：Vertex AI 端點的位置
  • MODEL_NAME：Vertex AI 嵌入模型的名稱
  • MODEL_VERSION：Vertex AI 嵌入模型的版本
  • MAX_ROWS：每個 RPC 的資料列數上限
  • EMBEDDING_VERSION_COLUMN：這個資料欄會管理用於回填嵌入項目的文字嵌入模型版本
  • FILTER_CONDITION：要套用的可分區篩選條件

以下是 products 資料表的填回查詢範例：

GoogleSQL 

UPDATE products
SET
  products.desc_embed = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL embedding_model,
      (SELECT products.description AS content)
    ) @{remote_udf_max_rows_per_rpc=200}
  ),
  products.desc_embed_model_version = 3
WHERE products.desc_embed IS NULL;

PostgreSQL

UPDATE products
SET
  desc_embed = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description)))
  ) /*@ remote_udf_max_rows_per_rpc=200 */ ->'predictions'->0->'embeddings'->'values'),
  desc_embed_model_version = 3
WHERE desc_embed IS NULL;

如要瞭解最佳做法，請參閱下列內容：

  • Spanner API 的預設 gRPC 逾時時間為一小時。視回填的嵌入數量而定，您可能需要增加這項逾時時間，確保 UPDATE 分區 DML 有足夠時間完成。詳情請參閱「設定自訂逾時和重試」。

效能和其他注意事項

回填嵌入資料時，請考慮下列事項，盡量提升成效。

節點數量

分區 DML 會在不同分區上平行執行指定的 DML 陳述式。如果執行個體有大量節點，您可能會在執行分區 DML 時觀察到配額錯誤。如果 Vertex AI API 要求的速度因 Vertex AI API 配額限制而受到節流，Spanner 會在分割 DML 交易模式下重試這些失敗要求，最多 20 次。如果發現 Vertex AI 的配額錯誤率偏高，請提高 Vertex AI 的配額。使用 GoogleSQL 時，您也可以使用陳述式層級的提示 @{pdml_max_parallelism=DESIRED_NUMBER} 調整平行處理。以下範例會將平行處理設為「5」：

GoogleSQL 

@{pdml_max_parallelism=5} UPDATE products
SET products.desc_embed =(
  SELECT embeddings.values
  FROM SAFE.ML.PREDICT(MODEL embedding_model, (
        SELECT products.value AS CONTENT
        )
  )
      @{remote_udf_max_rows_per_rpc=200}
),
products.desc_embed_model_version = MODEL_VERSION
WHERE products.desc_embed IS NULL;

資料欄中的文字大小

Vertex AI 嵌入模型對每個文字輸入的權杖數量設有上限。不同模型版本的權杖限制不同。每項 Vertex AI 要求可以有多個輸入文字欄位，但單一要求中的權杖數量有上限。如果是 GoogleSQL 資料庫，如果遇到「要求過大」訊息的 INVALID_ARGUMENT 錯誤，請嘗試縮減批次大小，避免發生錯誤。如要執行這項操作，您可以設定 default_batch_size，或在註冊模型時使用 @{remote_udf_max_outstanding_rpcs} 查詢提示。

傳送至 Vertex AI 的 API 要求數量

您可以使用查詢提示 @{remote_udf_max_outstanding_rpcs}，增加或減少從 Spanner 傳送至 Vertex AI 的要求數量。請注意，提高這項限制可能會增加 Spanner 執行個體的 CPU 和記憶體用量。如果是 GoogleSQL 資料庫，使用這項查詢提示會覆寫為模型設定的 default_batch_size。

監控回填進度

您可以使用系統洞察資訊主頁，監控從 Spanner 傳送至 Vertex AI 的要求數量、延遲時間和網路位元組數。

後續步驟