本頁面說明如何使用 Gemini Enterprise Agent Platform 文字嵌入 API,為儲存在 Spanner 的 GoogleSQL 方言資料庫和 PostgreSQL 方言資料庫中的資料,生成、儲存及更新文字嵌入。
文字嵌入是文字資料的向量表示法,可用於多種方式來尋找相似項目。每次您完成 Google 搜尋,或在線上購物時看到推薦內容,都是與這類系統互動。建立文字嵌入時,您會取得自然文字的向量表示法,也就是浮點數陣列。也就是說,所有輸入文字都會指派數值表示法。應用程式可以比較兩段文字向量表示法之間的數值距離,判斷文字或文字代表的物件之間的相似度。
您可以使用 Agent Platform 文字嵌入 API,透過生成式 AI 建立文字嵌入。在本教學課程中,您將使用 Agent Platform 文字嵌入模型,為儲存在 Spanner 中的資料生成文字嵌入。
如要瞭解哪些模型和端點位置可與 Spanner 搭配使用,請參閱「支援的模型和端點位置」。如要進一步瞭解文字嵌入,請參閱「取得文字嵌入」。
目標
在本教學課程中,您將瞭解以下內容:
- 使用 DDL 陳述式,在 Spanner 結構定義中註冊 Agent Platform 文字嵌入模型。
- 使用 SQL 查詢參照已註冊的模型,從 Spanner 儲存的資料生成嵌入。
定價
本教學課程使用 Google Cloud的計費元件,包括:
- Spanner
- Agent Platform
如要進一步瞭解 Spanner 費用,請參閱 Spanner 定價頁面。
如要進一步瞭解 Agent Platform 費用,請參閱 Agent Platform 定價頁面。
支援的模型和端點位置
在端點路徑中,指定使用 Agent Platform predict API 的文字嵌入模型,以及 Agent Platform 提供該模型的位置。Spanner 不會託管嵌入模型,也不會保留支援的模型清單。而是由 GoogleSQL 中的 ML.PREDICT 函式和 PostgreSQL 中的 spanner.ML_PREDICT_ROW 函式,將各項嵌入要求傳送至您指定端點路徑的 predict API。
在端點路徑中,Spanner 接受 us-central1 或 europe-west1 等區域位置、us 和 eu 多區域位置,以及 global 位置。模型 (而非 Spanner) 會決定哪些位置有效。Spanner 執行個體設定不會限制端點位置。如要縮短延遲時間,請選擇與 Spanner 執行個體位於相同區域的端點,或與多區域執行個體位於相同洲別的端點。
如果端點與執行查詢的 Spanner 伺服器位於不同區域,則須支付跨區域資料移轉費用。
下表列出使用 predict API 的 Agent Platform 發布者模型 ID。在端點路徑的 publishers/google/models/ 區段中,使用發布者模型 ID。
| 發布商模型 ID | 輸出維度 |
|---|---|
gemini-embedding-001 |
最多 3,072 |
text-embedding-005 |
最多 768 |
text-multilingual-embedding-002 |
最多 768 |
所有這些模型都僅在區域位置提供,例如 us-central1 或 europe-west1。這些服務都不支援 us、eu 或 global 位置。如需完整區域清單,請參閱「Google 模型端點位置」,並選取區域分頁標籤,例如「美國」或「歐洲」。在該頁面上,gemini-embedding-001 會顯示為「Gemini Embedding」,text-embedding-005 和 text-multilingual-embedding-002 則會顯示在「Embeddings for Text」下方。
在 GoogleSQL 中,您在 CREATE MODEL 陳述式中為模型指定的名稱是 Spanner 結構定義 ID,與發布者模型 ID 分開。
選擇模型前,請先前往「模型版本和生命週期」查看可用性和淘汰日期。
ML.PREDICT 和 spanner.ML_PREDICT_ROW 函式需要使用 predict API 的模型。gemini-embedding-2 模型改用 embedContent API,因此無法與這些函式搭配使用。這個模型也僅在 global、us 和 eu 位置提供。請改用 gemini-embedding-001。
在 GoogleSQL 中,CREATE MODEL 陳述式不會在您註冊模型時驗證發布者 predict 端點。在 PostgreSQL 中,spanner.ML_PREDICT_ROW 函式不會註冊模型。在這兩種方言中,如果 Agent Platform 不提供模型 ID、版本或位置,查詢時會失敗,並傳回 NOT_FOUND 錯誤。在 GoogleSQL 中,如果 OUTPUT 子句與回應不符,就會失敗並傳回 INVALID_ARGUMENT 錯誤。註冊或選擇模型後,請執行測試查詢,確認模型和位置是否正常運作。詳情請參閱「排解 Spanner Agent Platform 整合問題」。
生成及儲存文字嵌入
視使用的模型而定,生成嵌入可能需要一些時間。對於效能較敏感的工作負載,最佳做法是避免在讀寫交易中生成嵌入。請改用下列 SQL 範例,在唯讀交易中生成嵌入。
GoogleSQL
在 Spanner 註冊文字嵌入模型
在 GoogleSQL 中,您必須先註冊模型,才能搭配 ML.PREDICT 函式使用。如要在 Spanner 資料庫中註冊 Agent Platform 文字嵌入模型,請執行下列 DDL 陳述式:
CREATE MODEL MODEL_NAME
INPUT(
content STRING(MAX),
-- Optional: For models that support specifying task type.
task_type STRING(MAX),
)
OUTPUT(
embeddings
STRUCT<
statistics STRUCT<truncated BOOL, token_count FLOAT64>,
values ARRAY<FLOAT64>>
)
REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/PUBLISHER_MODEL_ID'
);
替換下列內容:
MODEL_NAME:Spanner 結構定義中的模型名稱,例如EmbeddingsModelPROJECT:託管 Agent Platform 端點的專案LOCATION:Agent Platform 端點的位置PUBLISHER_MODEL_ID:支援的模型和端點位置中的發布者模型 ID,例如gemini-embedding-001
Spanner 會自動授予適當權限。如果沒有,請查看模型端點存取控管。
生成式 AI 模型不支援結構定義探索和驗證功能。您必須提供與模型結構定義相符的 INPUT 和 OUTPUT 子句。文字嵌入 API 會將每項預測結果傳回為具有 embeddings 欄位的物件,其中包含 statistics 物件和 values 陣列。因此,上述 OUTPUT 子句會將 embeddings 資料欄宣告為 STRUCT (包含 values 和選用的 statistics),而非 ARRAY<FLOAT64> 類型。values 欄位會保留嵌入向量,因此本教學課程中的查詢會選取 embeddings.values。如果 OUTPUT 子句與回應不符,ML.PREDICT 呼叫會在查詢時失敗,並傳回 INVALID_ARGUMENT 錯誤。如要瞭解回應格式,請參閱「文字嵌入 API」。
生成文字嵌入
如要生成嵌入,請使用下列 SQL,將一段文字直接傳遞至 ML.PREDICT 函式:
SELECT embeddings.values
FROM ML.PREDICT(
MODEL MODEL_NAME,
(SELECT "A product description" as content)
);
如要為儲存在資料表中的資料生成嵌入,請使用下列 SQL:
SELECT id, embeddings.values
FROM ML.PREDICT(
MODEL MODEL_NAME,
(SELECT id, description as content FROM Products)
);
UPDATE Products p
SET description_embedding = (
SELECT embeddings.values
FROM ML.PREDICT(
MODEL MODEL_NAME,
(SELECT p.description as content, "RETRIEVAL_DOCUMENT" as task_type),
STRUCT(768 AS outputDimensionality)
));
SELECT p.product_id, p.name, p.description, COSINE_DISTANCE(
p.description_embedding,
(
SELECT embeddings.values
FROM ML.PREDICT(
MODEL MODEL_NAME,
(SELECT @user_query as content, "RETRIEVAL_QUERY" as task_type),
STRUCT(768 AS outputDimensionality)
)
)
) AS distance
FROM Products p
ORDER BY distance
LIMIT 5;
儲存文字嵌入
在唯讀交易中生成嵌入後,請將其儲存在 Spanner,以便與作業資料一起管理。如要儲存嵌入,請使用讀寫交易。
如果工作負載對效能較不敏感,您可以在讀寫交易中使用下列 SQL 生成及插入嵌入。儲存嵌入時,不一定要指定 vector_length,但建議用於 KNN 搜尋,且向量索引必須指定。將 VECTOR_LENGTH 替換為模型的輸出維度,例如 3072 或 768。如果資料欄儲存不同維度的向量,則可省略 vector_length:
CREATE TABLE Products(
id INT64 NOT NULL,
description STRING(MAX),
embeddings ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH),
) PRIMARY KEY(id);
INSERT INTO Products (id, description, embeddings)
SELECT @Id, @Description, embeddings.values
FROM ML.PREDICT(
MODEL MODEL_NAME,
(SELECT @Description as content)
);
PostgreSQL
生成文字嵌入
如要生成嵌入,請使用下列 SQL,將一段文字直接傳遞至 spanner.ML_PREDICT_ROW 函式:
SELECT
spanner.ML_PREDICT_ROW(
'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
'{"instances": [{"content": "A product description"}]}'::jsonb
) ->'predictions'->0->'embeddings'->'values';
替換下列內容:
PROJECT:託管 Agent Platform 端點的專案LOCATION:Agent Platform 端點的位置MODEL_NAME:Agent Platform 文字嵌入模型的名稱
spanner.ML_PREDICT_ROW 函式會傳回含有 predictions 陣列的 JSONB 物件。predictions 中的每個元素都有一個 embeddings 物件,其中包含 statistics 物件和 values 陣列。在本教學課程的範例中,-> 運算子會從 predictions[0].embeddings.values 路徑擷取嵌入向量。如需回覆格式,請參閱「文字嵌入 API」。
如要為儲存在資料表中的資料生成嵌入,請使用下列 SQL:
SELECT id, 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))))
) -> 'predictions'->0->'embeddings'->'values'
FROM Products;
替換下列內容:
PROJECT:託管 Agent Platform 端點的專案LOCATION:Agent Platform 端點的位置MODEL_NAME:Agent Platform 文字嵌入模型的名稱
UPDATE Products p
SET description_embedding = spanner.float64_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', p.description,
'task_type', 'RETRIEVAL_DOCUMENT'
)
),
'parameters', JSONB_BUILD_OBJECT('outputDimensionality', 768)
)
)->'predictions'->0->'embeddings'->'values'
);
SELECT p.product_id, p.name, p.description, spanner.COSINE_DISTANCE(
p.description_embedding,
spanner.float64_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', $1,
'task_type', 'RETRIEVAL_QUERY'
)
),
'parameters', JSONB_BUILD_OBJECT('outputDimensionality', 768)
)
)->'predictions'->0->'embeddings'->'values'
)
) AS distance
FROM Products p
ORDER BY distance
LIMIT 5;
替換下列內容:
PROJECT:託管 Agent Platform 端點的專案LOCATION:Agent Platform 端點的位置MODEL_NAME:Agent Platform 文字嵌入模型的名稱
儲存文字嵌入
在唯讀交易中生成嵌入後,請將其儲存在 Spanner,以便與作業資料一起管理。如要儲存嵌入,請使用讀寫交易。
如果工作負載對效能較不敏感,您可以在讀寫交易中使用下列 SQL 生成及插入嵌入。儲存嵌入時,不一定要指定 VECTOR LENGTH,但建議用於 KNN 搜尋,且向量索引必須指定。將 VECTOR_LENGTH 替換為模型的輸出維度,例如 3072 或 768。如果資料欄儲存不同維度的向量,則可省略 VECTOR LENGTH:
CREATE TABLE Products (
id INT8 NOT NULL,
description TEXT,
embeddings REAL[] VECTOR LENGTH VECTOR_LENGTH,
PRIMARY KEY(id)
);
INSERT INTO Products (id, description, embeddings)
SELECT @Id, @Description, 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)))
) -> 'predictions'->0->'embeddings'->'values'
));
替換下列內容:
PROJECT:託管 Agent Platform 端點的專案LOCATION:Agent Platform 端點的位置MODEL_NAME:Agent Platform 文字嵌入模型的名稱
更新文字嵌入
如要更新嵌入或即時擷取資料,請使用 UPDATE (GoogleSQL 和 PostgreSQL) 陳述式。
如要更新上例中的 Products 資料表,請使用下列 SQL:
GoogleSQL
UPDATE Products
SET
description = @description,
embeddings = (SELECT embeddings.values
FROM ML.PREDICT(MODEL MODEL_NAME, (SELECT @description as content))
)
WHERE id = @id;
更改下列內容:
MODEL_NAME:Agent Platform 文字嵌入模型的名稱
PostgreSQL
UPDATE
Products
SET
description = $1,
embeddings = 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', $1)))
) -> 'predictions'->0->'embeddings'->'values')
WHERE
id = $2;
替換下列內容:
PROJECT:託管 Agent Platform 端點的專案LOCATION:Agent Platform 端點的位置MODEL_NAME:Agent Platform 文字嵌入模型的名稱
後續步驟
- 瞭解如何使用 Agent Platform 向量搜尋 搜尋語意相似的項目。
- 如要進一步瞭解機器學習和嵌入,請參閱嵌入速成課程。
- 進一步瞭解 Agent Platform 文字嵌入模型。